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Assembly Language Lab 


Rose Curve Generator 


An application of mathematics which produces fascinating 
designs is the graphing of trigonometric functions using polar 
coordinates. Each function leads to a beautiful design which 
bears a strong resemblance to a flower, such as the rose. With its 
excellent graphics capabilities and superior user interface, the 
Macintosh is perfect for quickly plotting “rose” functions on the 
screen with a program simple enough that anyone can use it. The 
application described in this article takes full advantage of these 
capabilities to allow the user to experience the graphic beauty of 
trigonometry. 

Using Rose Curves 

After launching Rose Curves, a window will open in the 
center of the screen and the default function will be drawn inside. 
(See Figure 1) Both the standard apple menu and a Control menu 
will be in the menu bar. The apple menu contains the item “About 
Rose Curves...” and the names of all desk accessories available 
to the user from the System file. Under the Control menu are two 
options: Change Parameters and Quit. When the Change Para- 
meters item is selected a window similar to the one in Figure 2 is 
opened in the center of the screen. With this window the user can 
select the function to be drawn, choose the size of the drawing and 
indicate whether the drawing should be multilayered. Function 
and size are selected by clicking on the appropriate function 
name or size. For example, selecting cos (sin 100r) gives the 
design in Figure 3. If multilayered is selected, the function will 
be drawn at the original size and then shrunk repeatedly to create 
a “layered” effect, making the design more interesting: See 
Figure 4. 

Entering the Program 

Start up the Macintosh 68000 Development System. The 
startup disk should be titled ‘MDS1’ and the external disk 
'MDS2.' The applications Edit, Asm, Link, Exec and RMaker 
should be on MDS1 and a folder entitled ‘.D Files’ with 
SysEqu.D, ToolEqu.D, QuickEqu.D, and MacTraps.D inside on 
MDS2. To make Rose Curves work ona Macintosh 512 with the 
old ROM, FixMath.Txt and FixMath.Rel must also be in the .D 
Files folder (The information on where to get these two files is 
under How Rose Curves Works).  FixTraps.Txt and 
FixTraps.Rel are files which were distributed by Apple Com- 
puter under the Apple Software Supplement to aid assembly 
language programmers in calculating basic arithmetic and trigo- 
nometric functions. As the program is presented here, you have 
everything you need to type the program in and run it on a new 
ROM machine, since the FixTraps necessary for this program are 
explicitly defined with the ". TRAPS" statement at the start of the 
program. The program may also be entered into the new MPW 
assembler, or assembled with the Consulair C system, which 
includes the complete MDS assembler built-in. 
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Rose Curves £ == 


Fi gure 1 Default Rose Curve e Display 

To create the program, simply assemble the Rose.Asm 
listing. Then compile the resource file with RMaker. Finally 
execute the linker on the link file listing and the program object 
file and resource object file (both ".REL" files) will be linked 
together, an application generated, and the cute rose application 
icon should appear on the disk. Double click "Rose Curves" and 
your in business making fascinating polar coordinate art. 

How Rose Curves Works 

The program begins by initializing the standard managers, 
initializing its variables, setting up the menu bar and opening the 
window. The initialized variables are Equation, Scale, RealS- 
cale, Multilayered and drawn. Equation contains the item 
number of the selected function in the Change Parameters dialog. 
To obtain the real equation number, subtract 3 from Equation. 
Scale is the item number of the selected scale or "size" and 
RealScale is the actual scalar multiplied on each point before 
drawing it. Multilayered determines whether the rose will be 
layered. Finally, drawn is a boolean expression which deter- 
mines whether the window needs to be updated by redrawing the 
rose (false) or simply by copying the rose from the offscreen 
bitmap (true). The offscreen bitmap is also created in this routine. 
To create a bitmap, create an area in memory with space for a 
pointer, a word and a rectangle. In Rose Curves, this appears at 
the end of the program under the label windowBitMap. Now 
select the rectangle of the bitmap and calculate the rowbytes with 
the equation 
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x, 2/80 


rowbytes = іпЕССХ i. NEL 


If rowbytes is odd, round it up. Suppose our rectangle is 0, 
0, 50, 96 (remember that a QuickDraw rectangle is stored as y,, 
X,, Y» X,). Then rowbytes would be 14 and the bitmap would look 
like this: 
myBitMap DCL Ø pointer to bitmap storage 
DC 14 ;rowbytes 
DC 0, 0, 50, 96 ;boundsRect 


The size of the bitmap storage must be determined before it can 
be created. Use the equation 
Size = rowbytes * (y... Yi) 


To create the bitmap, use the following routine. 
поуе.1 #size,DØ 
-NewPtr 
lea myBi tMap, A1 
поме.1 A@,(A1) 


;allocate new pointer 


;put the pointer to the 
;Storage in myBitMap 


To copy apicture from the current window to myBitMap, use this 
routine 


pea aPor tC A5) ;storage for the port 
-GetPort ;get the current port 

move. | ePort(A5b), AQ — ;put the port pointer in AQ 
pea portBitsCA2) ;риѕћ ptr to port’s bitmap 
pea nyB i tMap іривһ ptr to our bitMap 

pea srcRect ;push srcRect 

pea dstRect ;push dstRect 

clr -CSP) ;SrcCopy 

clr.1 -(SP) jno mask region 

-CopyB i ts ;copy the bits 


Finally, remember to dispose of the bitmap's storage after 
finishing with it. This is accomplished simply with 
move.]  myBitMap, Ag 

-DisposPtr 


The EventLoop allows desk accessories to perform their 
periodic events by calling SystemTask and, if an event occurs, 
branches to HandleEvent which transfers execution to the appro- 
priate routine: Activate, Update, KeyDown or MouseDown. The 
Activate routine activates or deactivates the Rose Curves win- 
dow depending on what the user requested. Update updates the 
window by either drawing the curve or using _CopyBits, depend- 
ing on whether the curve had been drawn previously. KeyDown 
checks if the command-key was down when the KeyDown event 
occurred by testing bit eight of the ModifyReg. If bit eight equals 
one, a command-key was pressed and _MenuKey is called to 
determine the appropriate menuNumber and itemNumber for 
Choices, the routine which handles menu selections. 
MouseDown finds the area the mouse was clicked in using 
_FindWindow and jumps to the appropriate routine to handle the 
Click. 

Several other important routines are SystemEvent, InMenu, 
UnhiliteMenu, NextEvent InAppleMenu and ParameterChange. 
SystemEvent passes mouse clicks in system windows to the 
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system for it to handle. InMenu converts a mouse click in the 
menu bar to the correct menuNumber and itemNumber for 
Choices. Choices then calls InAppleMenu if the click was in the 
apple menu, calls ParameterChange if the first item in the Control 
menu was selected, or quits to the Finder if Quit was selected. 
UnhiliteMenu unhighlights all menus in the menu bar and Nex- 
tEvent returns to the EventLoop. InAppleMenu either displays 
the InfoAlert About Rose Curves... or opens the selected desk 
accessory using _OpenDeskAccessory. Finally, Parameter- 
Change opens the parameter dialog, hilights the buttons which 
correspond to the Equation, Scale and Multilayered variables and 
monitors the user’s actions until the dialog is dismissed with the 
OK or Cancel button. If OK was selected, ParameterChange 
updates the variables Equation, Scale, RealScale and Multilay- 
ered before closing the dialog and returning to the EventLoop. 
The heart of the program lies in the DrawRose subroutine. 
Before outlining how it operates, an explanation of the fixed- 
point math routines is needed. Fixed-point math is not as 
accurate as floating-point math, but much faster. With graphics 
programs, speed is often much more important than accuracy, 
especially when there is the possibility of losing the user’s 


Function: 
@ sin 4r 
C cos (2 sin r) 
Q cos (2 sin 2r) 


© cos (sin 100r) 
© cos (sin 8r) 
© cos (4 sin 2r) 
Size: 


Small O © O © © Large 


| ок, ) Г] Multilayered 


Figure 2: Control Dialog Box 


attention. Since Apple elected not to implement the fixed-point 
routines into the old toolbox, they released the file's FixTraps. 
Txt and FixMath.Rel in the Apple Software Supplement of Мау 
6, 1985. These filesare available from local user groups, bulletin 
boards, Apple dealerships or directly from Apple. FixTraps.Txt 
includes a nice description of the "toolbox additions" and 
FixMath.Rel contains the actual routines. To use the fixed-point 
routines on a Macintosh with the old ROM, type 'INCLUDE 
FixTraps.Txt’ at the beginning of your .Asm file. Also include 
the line ‘FixTraps’ after the name of the application under 
development in the .Link file. To use the fixed-point routines on 
a Macintosh with the new ROM, simply define the trap using 
TRAP at the beginning of the ASM file as we did in our listing 
here. The complete list of new fixed-point traps is as follows: 


Long2Fix  $A83F 
FracSin $4848 
FracSqrt $4849 


FracMul $A84A 
FracDiv $484B 
FixAtan2 $A8 18 
FixDiv $484D 
Fix2zLong . $4840 
Fix2Frac $4841 
Frac2F ix $4842 
Fix2X $4843 
X2F ix $4844 
Frac2X $4845 
X2Frac $4846 
FracCos $A847 


The fixed-point routines support three types of numbers: 
longint (long integer), fixed, and fract (fractional). Type longint 
represents integers between 32147483647, type fixed represents 
fractional quantities between +32768 with about 5 digits of 
accuracy and type fract represents fractional quantities between 
+2 with about 9 digits of accuracy. Rose Curves uses  FracSin, 
_FracCos, FixMul and _FracMul to perform its arithmetic 
operations. These routines work like any other toolbox trap: 
space is cleared on the stack for the result, the parameters are 
pushed on the stack and the trap is called. The Pascal definitions 
for these routines are 


function FracSin€ x : Fixed ) : Fract 
function FracCos( x : Fixed ) : Fract 
function FixMulC x, y : Fixed ) : Fixed 
function FracMulC x, у: Fract ) : Fract 


With _FixMul and _FracMul it is possible to pass parame- 
ters of different types than specified. For example, one could 
pass x as type longintand y as type fixed to_FixMul and the result 
would be type longint. The following table contains the result 
types for multiplying different types using _FixMul and 
_FracMul. 


_FixMul _FracMul 

x Y result X у result 
fixed fixed fixed fract fract fract 
longint fixed longint longint гасі longint 
fixed longint — longint fract longint — longint 
fract fixed fract fixed fract fixed 
fixed fract fract fract fixed fixed 


Note: To convert a number to type Fract, multiply it by 
65536. То сопуеп а number to type Fixed, multiply it by 32768. 

DrawRose begins by changing the cursor to a watch, setting 
the counter to 721 steps (1 + 360? x 1/increment), the increment 
to 572 (.5? in fixed-point radians) and the present angle to O. It 
then loops until the counter is zero, evaluating the current 
function (bsr EvalFunction), converting the function result to 
rectangular coordinates and scaling and centering the points. 
After completing each layer, the program decreases the scale by 
20 and redraws the curve if multilayered was selected. After 
drawing all of the layers, the variable drawn is set to true and the 
image in the window is copied onto the offscreen bitmap for 
future update events. 

Possible Modifications 

Rose Curves could be improved in several ways. The most 
obvious way would be to add more functions to the program. To 
accomplish this, add the “function” buttons in the Rose.R file and 
add the subroutines to evaluate the new functions to Rose.Asm. 
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Note that the displacement to the function must be included in the 
equation table for the new subroutine to be executed. To do this, 
add the line DC functionLabel-EquationTable after the line DC 
Six-EquationTable. As more functions are added, keep adding 
the labels to the equation table. The second improvement would 
be to decrease the time required to draw the rose when multilay- 
eredis on. To do this, copy the image of the rose into an offscreen 
bitmap using _CopyBits after the first rose has been drawn. Then 
shrink CopyBits' dstRect and copy the rose from the offscreen 
bitmap onto the screen. Although many times faster, this method 
greatly reduces the accuracy with which layers are drawn since 
they are being scaled by  CopyBits, not mathematically graphed. 
An option to this problem would be to include a checkbox in the 
Change Parameters dialog titled ‘Accurate Multilayers.’ If 
selected, Rose Curves would draw the layers using its normal 
drawing routine. If not, Rose Curves would use the copy-and- 
shrink method, thus giving the user the choice of accuracy or 


= Rose Curves === 


Figure 3: y = cos (sin (100r) ) 


;File: Rose. Asa 

“Rose Curves draws curves expressed as а 

; function of г and theta. 

,Mritten by Victor Barger on April 2, 1986. 


INCLUDE — MacTreps.D 
INCLUDE — QuickEqu.D 
INCLUDE — ToolEqu.D 
| .trep FracMul %А84А ;New Roms 
.trap FracCos $4847 
.trap -Ргас$1п $4848 
Radians EQU D3 


TopButton EQU D3 


BottomButton EQU D4 
Modif yReg EQU D4 
Increment EQU D4 


© The Essential MacTutor, Vol. 3 


== hose Curves = -FlushEvents 
= -InitWindows 
- Ini tMenus 
clr.1 -XSP) 
-InitDialogs 
-TEInit 
-InitCursor 
rts 
InitVariables 
move """3,Equation(CA5) 
move . "InitialScale,ScaleCAb) 
move.1*RealInitScale,RealScaleCA5) 
clr  Multilagered(A5) ;hot multilayered 
move. 1 #11528,D0 
_NewP tr ;create а new bit map 
lea  windowBitMap,A1 
поуе.1А0,(А1) remember the pointer 
clr дганп(А5) not drawn yet 
rts 
SetupMenu 
сіг.1 -CSP) 
move *AppleMenulD,-CSP) 
_GetRMenu ;get the apple menu 
move. 1 (SP), App]leMenuCA5 ) 
move. 1 (SP),-CSP) 


Ч 
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Figure 4: Getting Fancy! cos (4 sin 2r) cir -(SP) 
1 1 _Inser tMenu ;insert the menu in the menu bar 
with multilayered checked. aep БИР 
MenuReg EQU 05 -AddResMenu ;add the DA's to the apple menu 
Counter EQU D5 
CheckBox EQU 06 сіг.1 -CSP) 
MenuItemReg EQU 06 move ControlMenuID, -CSP) 
FuncResult EQU M -Ge tRMenu ;get the control menu 
clr -($Р) 
AppleMenuID EQU 1 _Inser tMenu ;insert the menu in the menu bar 
ControlMenuID EQU 2 
-DrewMenuBar ;draw the new menu bar 
ParamD1gID EQU 2000 rts 
DrawWindID EQU 2001 уен нын ане ныл ны шыны ны ышын ac 
InfoAlertID EQU 2002 Setup indow 
с1г.1 -CSP) 
InitialScale EQU 13 move *DrawWindID,-CSP) 
RealInitScale EQU 460 pea — WindowStorageCA5) 
rnc ME MMC M MU m шышы ан шы ныр D CE nove. 1#-1,-С$Р) 
Start _Ge tNewW indow ;get the RoseCurves Window 
bsr  InitMenagers ;initialize managers nove. 1 CSP),DrewPtr CAS) 
bsr  InitVeriebles ;initielize variables -SetPort ;set the new grafport 
bsr SetupMenu ;setup the menu rts 
bsr SetupWindow ;draw the window Pl a a кін жаса анда DLL D DLE киса oA 
HandleEvent 
EventLoop move Modify, ModifyReg 
Sys temTask ;periodic actions for da's move What,DØ 
cir -($Р) edd 00,00 
move *$OFFF,-CSP) move Еуеп(Та51е(002,00 
pea — EventRecord jmp X EventTebleCD0) 
-GetNextEvent дес the next event 
move (SP)+,DØ EventTable 
beq.s EventLoop ;no event, loop back DC NextEvent-EventTable 
bsr HandleEvent — ;hendle the event DC —— MouseDown-EventTable 
beq.s EventLoop АҒ Ø, continue; else quit DC — NextEvent-EventTeble 
rts DC KeyDown-EventTable 
DC NextEvent-EventTable 
Beep DC KeyDown-EventTable 
move #]2,-($Р) DC Update-EventTable 
_SysBeep DC Nex tEvent-EventTable 
rts DC Activate-EventTable 
a a a DC  NextEvent-EventTable 
Ini tWanagers DC Nex tEvent-EventTab le 
pea -4(А5) | xg cq pu ul E MI CD PRS 
_InitGraf Activate 
-InitFonts move. 1 DrawPtr(A5), D8 
move . 1 $0000FFFF , D8 стр.1 Message,D@;was it our window? 
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bne — NextEvent jno, get next event pea — EventRecord ;ptr to the event record 
btst %0 ModifyReg X ;activate? move. 1 WWindow, -CSP) ;push window ptr 
beq  NextEvent ;no, deactivate SystemC] ick ; let system take care of it 


bre — NextEvent jnext event 


SetOurPort рса зене SR See MM CLE DEI 
move.1DrewPtrCA52,-CSP) ;ривһ pointer to draw window InMenu 
-SetPort зей our port с1г.1 -(GP) ,Space for menu choice 
рга — NextEvent move. Point,-CSP) ,mouse at time of event 
аккан анага қын EID ELE CC ECC CLE -MenuSelect jmenu select 
Update move (SP)+,MenuReg ;preserve menu 
move . Message, 00 ;get the window ptr move (SP)+,MenultemReg ;ргеѕегуе menu item 
cmp.1 DrewPtr(CA52,00 
bne NextEvent Choices 
cmp %2,MenuReg мав it the control menu? 
tst — drewnCA5) bne.s NotQuit jno 
bne.s copyIt cmp #2, MenuItemReg ;Quit selected? 
move.lDrewPtr(A5),-CSP) X ;push window ptr bne.s NotQuit jno, continue 
-SetPort ;set the port bsr — UnHiliteMenu junhilight the menu bar 
move. 1DrewPtrCA5), -CSP) QuitRoutine | 
-BeginUpdate move. ] DrawPtr(A5),-(SP) ;риѕћ ptr to draw window 
move. 1 DrawPtr(A5),-CSP) -CloseWindow ;close the window 
_EndUpdate move . 1 windowBi tMap , Ad 
pea — windowRect -DisposPtr ;dispose of the bitmap 
-EreseRect move %-1,00 jsay it was Quit 
bsr DrawRose ,draw the rose rts 
bre — NextEvent 
NotQuit 
copyIt сор — *1,MenuReg jin apple menu? 
move. 1DrawPtr(A5),-CSP) ;ривһ window ptr beq.s InAppleMenu ,yes, go do apple menu 
-SetPort jset the port cmp %2,MenuReg jin file menu? 
move. 1 DrawPtr(A5),-CSP) beq ParameterChange уез 
-BeginUpdate 
pea windowBitMap дес the rose from the bitMap ChoiceReturn 
move.1drewPtrCA52,A0 bsr — UnHiliteMenu punhilight the menu bar 
pea portBitsCAd) ;put the rose in our window ;fall through get next event 
pea — windowRect бәле rect for src and dest 777777--------------------------------------------------- 
pea — windowRect NextEvent 
clr -($Р) ,SrcCopy moveq #0,0@ ;,Say it's not Quit 
с1г.1 -($Р) jno maskRgn rts ,return to event loop 
-CopyBi ts сору It 77--77-------------------------------------------------- 
move. 1DrewPtrCA5),-CSP) UnhiliteMenu 
-EndUpdate clr  -(SP) 3811 menus 
bra — NextEvent -HiL iteMenu ,unhilite every one 
Р кай Жыйна а аас CMM CDM LL LC E EE rtis 
KeyDown "armrx oe ar са M te eee 
бізі %8,ModifyReg jis the command key down? InAppleMenu 
beq NextEvent ‚по, exit cmp — *],MenuItemReg 
сіг.1 -CSP) ,Space for menu and item beq.s Info 
move M Message*2, -(SP) ;get character 
-MenuKey ,see if its а command move. 1 AppleMenu(A5), - CSP) 


move (SP)+,MenuReg jpreserve menu 


move MenultemReg, -CSP) 


move (SP)+,Menul етед 
bra.s Choices 


clr -($Р) 

nove. 1Point,-CSP) 

pea — WWindow 

-F indWindow 

move (SP)+,DØ 

edd 00,00 

move WindowTebleCD25,D0 
jmp  WindowTableCD0) 


WindowTable 
DC NextEvent-WindowTable 


DC InMenu-WindowTable 


jand Menu item 


7 
MouseDown 


;space for result 

,get mouse coordinates 
;push event window 

;find the window 

;get region number 

;*2 for index into table 
;point to routine offset 
;jump to routine 


jin desk (not used) 
jin menu bar 


DC SystemEvent-WindowTable ;іп system window 


DC NextEvent-WindowTable 
DC NextEvent-WindowTable 
DC NextEvent-WindowTable 


jin drag (not used) 
jin grow (not used) 


DC QuitRoutine-WindowTable ;іп go away 


SystenEvent 
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jin content (not used) 


pea DeskName 
-GetItem 

clr -($Р) 
pea DeskName 
-OpenDeskAcc 
move (SP)+, DØ 


RestoreOurPort 
bsr SetOurPort 
рга ChoiceReturn 


,get name of the desk accessory 


,open the desk accessory 


Info 
clr -($Р) 
move "InfoAlertID,-CSP) 
сіг.1 -($Р) 
-Alert 


move (SP)+,D0 


bra ВеѕіогедигРогі 


ParameterChange 
clr.1 -(SP) 


jhandle the infoAlert 


move &Рагат01910,-С5Р) 


pea DStorage 
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move.13-1,-CSP) 
-GetNewDialog дек the dialog 
move . 1 CSP2,PerenD1gPtrCA5) іргезегуе the dialogPtr 


-SetPort ;set the port 


move EquationCA5),TopButton — ;TopButton = current button 
jhighlighted in top section 


move TopButton, Dé 

bsr  FindButton ;Sub. to return handle 
move. 1 itemHandleCA5),-CSP) 

move 91,-CSP) 

-SetCtlValue ;highlight the button 


move ScaleCA5),BottomButton ;BottomButton = current 


; button in bottom section 


move BottomButton, D8 

bsr  FindButton 

поуе.1 itemHandle(A5),-CSP) 

move 81,-CSP) 

-SetCtlValue jhighlight the button 


move Multi layeredCA5), CheckBox 

move %17,00 

bsr FindButton jget handle to check-box 
move. 1 itemHandleCA5),-CSP) 

move CheckBox,-CSP) 


-SetCtlValue jcheck or uncheck it 
RepeatLoop 

сіг.1 -CSP) 

pea  ItemHit 

-ModalDialog jmodal dialog 

move ItemHit,D! 

cmp 2,01 jwas it Cancel? 

beq Done уез 

cmp 81,01 jwas it OK? 

beq  SetNewParems jyes 

cmp #89,D1 jwas it in the bottom set? 

bge.s BottomSet Уез 


move TopButton, DO 

move D1, TopButton вес new button number 
bsr  FindButton зде handle to last button 
move. 1 itemHandle(CA5)2,-CSP) 

clr  -(SP) 

-SetCtlValue junhighlight last button 


move TopButton,D0 

bsr  FindButton 
move.litemHandleCA5),-CSP) 
move #],-($Р) 


-SetCtlValue jhighlight new button 
bra.s RepeatLoop 

BottonSet 
cmp #14,D1 jin bottom set? 
bge.s CheckForBox ‚по 


move BottomButton, 00 

move Di,BottomButton 

bsr  FindButton jget handle to last button 
move . 1 i temHand1le(A5),-CSP) 

clr -($Р) 

-SetCtlValue junhighlight last button 


move BottomButton, Dd 

bsr  FindButton 

move.litemHandle(Ab),-CSP) 

move #],-($Р) 

-SetCtlValue ;highlight new button 
bra RepeatLoop 
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CheckForBox 
cmp #]7,01 ;click in the check box? 
bne RepeatLoop 
cmp #1, CheckBox 
bne.s NotOne 
move 480 CheckBox 
bra.s SetCheck 


No tûne 
move #1,CheckBox 
SetCheck 
move %17,00 
bsr  FindButton jget handle to check-box 
поуе. 1 itemHandleCA5), -CSP) 
move CheckBox,-(SP) 
-SetCt Value ;check or uncheck it 
bra RepeatLoop 


SetNewParans 
clr  drawnCA5) 
move TopButton,Equation(A5)  ;set new equation number 
move BottomButton,ScaleCA5) ;ѕеї new scale 
move CheckBox,Multilayered(A5) jset multilayered 
move 5са1е(А5),00 
sub 99,00 
asl.] 82/00 
move. 1ScaleTable(D@),RealScaleCA5) ;1оок up real scale 


Done 
move. 1 ParamD1gPtrCA5),-CSP) 
-CloseDialog ;close the dialog 
bre X RestoreOurPort 


ScaleTable 
DC.L 140,220 ,300,380 460 
FindButton 
nove. 1ParamD1gPtrCA5),-CSP) 
move 00,-(ӘР) 
pea — itemType 
pea — itemHandleCA5) 
pea dispRect 
-GetDItem дес handle to itemnumber in DØ 
rts 
{о convert а fract number to type frect, multipy by 65536 
DrewRose 
сіг.1 -CP) 
move #4,-(SP) 
-GetCursor ;get the watch cursor (10-4) 
move. 1 (SP )+,00 
move. 1 DØ, Ad 
move. 1 САЙ), СР) 
-SetCursor вес the new cursor 


move.lRealScale(A52,-CSP) ;preserve the realScale 
DrawRosel 


move  !720,Counter ;721 steps (360 x 2) 
move. 1 #572, Increment 3572 = .5° increment in radians 
; C .5n/180)*65536 
moveq *9,Radians jpresent degrees 
nextDegree 
bsr EvalFunction evaluate fn r(Redians) 
Sub %14,5Р 
move. Redians, -CSP) 
-FracSin 
move. FuncResult,-CSP) 
-FrecMul ‚у = fn rCRadians) * sinCRadians) 
nove. 1 RealScale(A5), -CSP) 
-FixMul у = у * realScale 
-HiWord 
move (SP)+,yCA5) jy = intCy) 


Sub — *14,9P 

move. 1Radians, -CSP) 
-FracCos 

поме . lFuncResult, -(SP) 
—FracMul ;X = fn rCRadians) * cos(Radians) 
move . 1 RealScaleCA5), -CSP) 

-FixMul Хх 
-HiWord 

move ($Р)+,х(А5) jx = int(x) 


x * realScale 


move х(А5),00 
edd —5154,D0 
move 00,-С5Р) jx =x + 154 
move  yCA52,D0 
edd 8144,00 
move  D0,-CSP) НТ 


у + 144 


tst Вадіапѕ 
bne.s NotFirst 


-MoveTo moveto x,y if first point 
bra.s Skip 

NotFirst 
-LineTo else lineto x,y 

Skip 


add.1 Increment,Redians  ;Redians = Radians + Increment 
дога Counter,nextDegree ;1оор back 

cmp — 81,Multilayered(A5) ;another layer? 

bne.s NoExtraLayers ;no 

поме. 1 #20, D8 

sub. 1 D@,RealScaleCA5) 
стр.1 RealScaleCA52,00 
bne X DrewRosel 


,decrease the real scale by 20 
;is the real scale = 29? 
jno, do next layer 


NoExtraLayers 
move *1,drawn(A5) 
move. 1 drawPtr(A5), Ад 
pea portBitsCAd) 
pea — windowBitMap 
pea — windowRect 
pea — windowRect 


; the rose has been drawn 


;put the rose in our window 
;get from offscreen bitmap 
;зате size windowRect 


clr -($Р) ;srcCopy 
clr.1 -CSP) jno mask region 
-CopyBi ts ;copy the bits 
move . 1 (SP)+,RealScaleCA5) 
-InitCursor 
rts 
EvalFunction 
move EquationCA5),Dd 
sub %3/00 
edd 00,00 


move EquationTable(DØ), DØ 
jmp  EquationTableCD2) 


EquationTable 
DC One-EquationTable ;ѕіп 4r 
DC Two-EquationTable ;с05 (2 sin г) 
DC Three-EquationTable ;cos (2 sin 2r) 
DC Four-EquationTable ;соѕ (sin 100r) 
DC Five-EquationTeble ;cos (sin 8 г) 
DC Six-EquationTeble ;соѕ (4 sin 2r) 


None 

move. 180, FuncResult 

rts 
------------------------------------------------------- 
One 

,Sin 4r 

сіг.1 -CSP) 

move . 1 Radians, 00 

аѕ1.1 82/00 

8 


move.109,-CSP) 

-FrecS in 

move. 1 (SP)+,FuncResult ;fn rCRadians) = sin (Radians * 4) 
rts 


;соѕ (2 sin г) 

subq #8,5Р 

move. 1 Radians, -CSP) 
-FrecS in 

поуе.1 (5Р),00 

аѕг.1 87,00 

а5г.1 86,00 

поуе. 100, (ӨР) 
-FrecCos 

move. 1 (SP)+,FuncResult 
rts 


convert to fixed x 2 


;fn rCRadians) = cos (2 sin г) 


;соѕ (2 sin 2r) 
Subq &8,5Р 
move. 1 Radians, 00 
аѕ1.1 81,00 
поуе.100,-(5Р) 
_FracSin 
move. 1 (SP), DØ 
asr.] 87,00 
asr.| %6,D0 
move. 100, (SP) 
-FrecCos 

move. 1 С5Р )+, FuncResult 
rts 


convert to fixed x 2 


‚Їп rCRadians) = cos (2 sin 2r) 


;cos (sin 100г) 

Sub  '12,SP 

move. 1 Radians, -CSP) 
move. 1 32768020, -(SP) 
-FixMul 

-FrecS in 
похе. 1 СР ),00 

азг.1 87,00 

аѕг.1 87,00 

move. 100, (SP) 
-FracCos 

move. 1 С5Р )+, FuncResult 
rts 


convert to fixed 


;fn rCRadians) = cos (sin 100г) 


;соѕ Csin 8 г) 
subq  *8,SP 
move. 1 Radiens,D0 
а$1.1 83,00 
move. 1D8,-(SP) 
racsin 
move.1(SP),D8 
аѕг.1 *7,D0 
esr.] "T7,D0 
move. 1 DØ, (SP) 
-FracCos 

move. 1 (SP )+,FuncResult 
rts 


‚Рп rCRadians) = cos (sin 8r) 


;соѕ (4 sin 2r) 
subq #8,5Р 
move. 1 Radians, DØ 
а51.1 81/00 
move.1D0,-CSP) 
-FracSin 
move. 1 (5Р),00 
азг.1 87,00 
аѕг.1 85/00 
move. 100, (SP) 
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-FracCos 170 88 186 192 Type ROSE = GNRL 
move.1(SP)+,FuncResult — ;fn r(Radians) = cos (4 sin 2r) Multi layered т 
rts 
aa деін сі Local Variables ----------------- ,2002 (32) 4D526F 73 
EventRecord 3 65204315 
What: DC Ø BtnItem Enabled 72766573 
Message: DC.L Ø 128 112 148 172 20163 12E 
When: DC.L 0 OK 302Е2020 
Point: DC.L 0 51126914 
Modify: DC Ø StatText Enabled 14656E20 
Window: DC.L Ø 8 56 42 237 62792056 
Rose Curves v1.1 69637 46F 


windowRect DC 8,0,288,308 Written by Victor Barger | 72204261 


windowBitMap ODC.L Ø 72616572 

DC 40 StatText Enebled 20116914 

DC 90,0,288,308 56 8 107 287 68201468 

Rose Curves was originally 6F 756768 

ItemHit DC Ø written on April 3, 1986. 74713206F 

itemType DC Ø 66204C6 1 

dispRect DC  0,0,0,0 15126 120 

DStorage DCB DWindLen,@ Type DLOG 43687269 

DeskName DCB 16,0 ,2000 T314696E 
je«sesssescessse Application: Globals ================ 652E 


10 115 273 397 


WindowStorage DS  WindowSize 


,Storage for drew window 


DrewPtr DS.L 1 ;pointer to draw window Visible NoGoAway Type ICN® = GNRL 
App leMenu DS.L 1 ;apple menu 1 ‚ 12 
Equation 05 1 ,equation number 0 ‚Н 
Scale DS 1 sscale 2000 000 10000 
RealScale DS.L 1 ;longint real scale 00028000 
MultiLayered DS 1 ;nultilagered (Ø = false, 1 = 00044000 
ігие) Type WIND 00082000 
ParamDlgPtr DS.L 1 ;pointer to the parameter dialog ,2001 (4) 00 10 1000 
itemHendle DS.L 1 ;itemHandle Rose Curves 00200800 
y DS 1 ;y-value 44 102 331 410 00580400 
X DS 1 ;x-value Visible GoAway 00448200 
drewn D$ 1 0 Ø 12A8 100 
—————Á———— 6 02 110080 айаш. 
мш | ттт 
ЛЕН ЕЕ ie at TOME 
i ,2002 (32) 20040008 üFFFFFEF 
Type DITL Rediolten Enabled D em SE ITO O7FFFFFF 
чы ЫИ 4444 40908041 riii 
BtnItem Enabled Redioltem Enabled 970 RI OO7FFFFF 
ОРО ЭР Роло PA) 04223001 piii 
OK \14 022 10007 00-800 
BtnItem Enabled RadioItem Enabled ADOU V ROSE: CURVES: "oeil 0007Ғ000 
168 216 188 276 136 120 152 141 “ры 0003Е00@ 
ne 20 002002 1F eee 
, 00 100407 
Radioltem Enabled RedioItem Enabled Contro! 
RUP 00022000 
RadioItem Enabled RedioItem Enabled x rien 
64 24 80 121 136 168 152 226 *Define the BNDL. FREF and s /Output Rose Curves 
ЭО а ROSE for the desktop icon. | 00010000 || pose 
RadioItem Enabled el Ыыы Гра BNOL Р "T 
88 24 104 132 
; ‚ 128 000ҒЕ000 Se eee 
cos (2 sin 2r) Size: ae аге ШИЕ ROSE 
Radioltem Enabled StatText Enabled 11. pb Rose_Rsrc 
40 160 56 272 16 8 32 72 FREF QOFFFEOQ 
cos (sin 100г) Function: 8 128 D IFFFFOO 5 
Rediolten Enabled StatText Enabled — IEEE 
64 160 80 254 136 28 152 68 5 ФЕРЕЕЕЕЙ 
каш) e APPL Ø 1FFFFFFO 


RedioItem Enabled 


ChkItem Enabled 
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ToolBox Tricks 
Not So Standard File Dialogs 


Last month I discussed how INIT resources could be de- 
bugged using TMON, as I did in developing my Set/Boot Paths 
desk accessory, used in TML Pascal 2.0. Set Paths allows the user 
to specify what path to use via what I prefer to call the Not-So- 
Standard File dialog. It's Not-So-Standard because it doesn't 
display file names at all, only folder names. That's not so weird 
(nor is it particularly difficult to code), but the "Open" button has 
become "Select" and, the tricky part, double-clicking ona folder 
name opens it exactly the way you'd expect, whereas highlighting 
a folder name and clicking on "Select" returns you to your 
program with pertinent information about the selection. 

Experienced Standard File hackers may knot their brows at 
this (as I did when I was asked to do it that way) because they 
know that the Standard File internally coerces double-clicks on 
names to be a single click followed by a click on the "Open" 
button, so that the Standard File hook can filter double-clicks. 
The trick, then, is being able to use a user-written Standard File 
hook to distinguish between a double-clicked name and a se- 
lected name followed by a "Select" click. 

Note that my solution isakludge by just about any definition 
of the word, and would be universally spurned (even by me) were 
it not for one simple, overriding fact: it does NOT rely on internal 
knowledge of Standard File's workings AT ALL, and it was 
simple and obvious enough to have gone from concept to im- 
plementation in less than twelve hours (an important considera- 
tion for me; I modemed the resultant files to TML Systems 
Sunday evening; TML Pascal 2.0 started shipping the next day)! 

To start off on an embarrassing note, in the process of 
writing Set Paths I discovered a bug in my McAssembly Pascal 
interface macros. Those were published in MacTutor Vol. 2, No. 
3, in March 1986, which says two things to me: I need to be more 
careful in my testing of things before I publish them, and no one 
has done anything significant with those macros, otherwise they 
would have encountered the bug and, hopefully, written a letter 
to the editor about it! I'm profoundly disappointed... 

Anyway, the bug is in the "Exit" macro. There's aline which 
is responsible for adjusting the stack back to normal by dropping 
input parameters. It says: 


edd.1 8 .fsize-.perms,sp 


This is a definite boo-boo, because it totally neglects the 
space that we allocated for the stacked A6 register and the return 
address of the function. The line SHOULD read: 

edd.| —.fsize-.perms-8,sp. 


Boy, do I feel appropriately chastized! 
Having cleared that up, I can talk safely about using those 
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macros to implement the Not-So-Standard File dialog. 

First we need to come up with a way to display NO files at 
all. The first time I tackled this, о! Paul thought he'd be tricky and 
just set the numTypes parameter to _SFGetFile to zero, thereby 
forcing _SFGetFile to ignore all files, right? Wrong! Even 
though I had a typeList consisting of all zeros and anumTypes of 
zero, SFGetFile insisted on displaying ALL files on the volume, 
and it took forever to do it, too! 

I decided to do something about the INCREDIBLY slow 
response I was getting from the above scheme. Besides, it didn't 
work! I changed numTypes to one and used a fileType of '????' 
to get as few files as possible (theoretically zero). Since every so 
often you will indeed see a file of type ????' it behooved me to 
ensure that they didn't show up in the file list. To do that I had to 
use that fileFilter that I had tried to avoid. 

The fileFilter proc is, like most such things for the Macin- 
tosh, designed with the expectation that it will be written con- 
forming to Pascal-style parameter passing conventions. It is (in 
Pascal terms, anyway) a function, nota procedure, since it returns 
a value. It takes one parameter, a pointer toa low-level parameter 
block a 14 the file system, and returns a boolean. It seems a little 
backwards: the boolean should be TRUE if the file is NOT to be 
displayed, and FALSE if the file IS to be displayed. So, since we 
want to display NO files, we should simply set the boolean to 
TRUE and we are done! In Pascal this would look something like 
this: 


mbly 


FUNCTION MyFileFilterCPB : ParamBlockRec;) : BOOLEAN; 


BEGIN (MyFileFilter) 
MyFileFilter := TRUE; 
END; (MyFileFilter) 


In McAssembly, with my Pascal macros, it's almost as 
easy: (See MacTutor Vol. 2, No. 3 March 1986 for the 


definition of these Macros.) 
MyF i leFilter EQU ы 
SFBegin 
WordResult MyF il terResult 
Long MyParamB lock 
SFEnd 
Enter 
move.w ®-1,MyFilterResult 
Exit 


The combination of the file type of '????' and the above 
fileFilter works like a charm; by golly, no files show up! 
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SFHook 

The remaining magic is in an underdiscussed piece of code 
called a SFHook. Apple describes the SFHook as something that 
can be used to make a non-standard get or put file (which I almost 
do) or to make the normal one behave in non-standard ways 
(which is EXACTLY what I do)! 

The SFHook is also a Pascal-like entity; it takes two para- 
meters; the item number (an integer), and the DialogPtr to the 
Standard File dialog. It returns an integer (an item number also, 
although it may or may not be the same as the one that was passed 
to it)! 

The SFHook is called constantly throughout the operation 
of the Standard File dialog; it's called before the dialog is drawn, 
it's called when there are significant events, and it's even called 
when there are NO significant events! 

The key to understanding the Standard File dialog as it 
applies to writing a SFHook is the item number. The item number 
isordinarily simply the item number of whatever the user clicked 
on in the dialog box. In addition to that there have always been 
afew "phony" items numbers, such as item # 100 (which is what 
was passed when nothing interesting was going on) or keystrokes 
(item # 1000 plus the ASCII value of the key). Another useful 
value is -1, which is the value passed before the dialog is 
displayed. By trapping on this value we can do neat things like 
changing the title of the "Open" button to "Select." You'll see an 
example of that a bit later. 

The introduction of HFS added a whole new wrinkle to the 
issue of the Standard File dialog. It had to be expanded in a way 
that retained the power and flexibility of the original design, yet 
also remain upwardly compatible. WDRefNum's anda few new 
phony item numbers fit the bill rather nicely. 

As all users of the Standard File dialog are aware of at one 
level or another, "Opening" a folder doesn't return you to the 
application, it simply makes that folder the current directory and 
shows you the files in it, etc. You must open a FILE to get back 
from  SFGetFile. 

Internally what happens is that opening a folder passes a 
phony item # 103 to the SFHook, as opposed to a file open, which 
passes item # 1 (the item # of the "Open" button). So we could 
catch the 103, coerce it to a 1, and passit back. The problem there, 
of course, is the one mentioned before: double-clicks on file- 
names and filename select/"Open" click sequences are equiva- 
lentby the time you get to the SFHook! The result is that double- 
clicking on a foldername returns from _SFGetFile just as surely 
as selecting one and clicking "Open" does! 

Argh!!! 

Ok, enough beating around the bush. Obviously the solu- 
tion to the problem is to find out which item we clicked on, the 
file list or the "Select" button. I decided that the Mac was fast 

enough that I could determine within the SFHook where the 
mouse was, check to see if it was over the file list and, if it was 
not, coerce the 103 to a 1. Fortunately, one of the things passed 
to the SFHook is the DialogPtr, making calls to _GetDItem 
possible. Among other things, GetDltem returns the viewRect 
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of the item - just what the doctor ordered!  GetMouse gives us 
our mouse location in local coordinates (another stroke of luck) 
and PtInRect answers the burning question: are we pointing to 
this item or aren't we? 

Pulling it all together into a nice, not-so-neat package gives 
us the following: 


UseSF move.w 8 190, -Csp) Top = 100 
move .w 8 100, -(sp) Left = 100 
pea PromptString Use promptstring 
pea myFileFilter Use brief fileFilter 
move.w 81,-Csp) No. of filetypes 
pea MyList Point to my list 
pea myD 1 gHook Point to our dighook 
pea myRep lyRec Point to reply rec 
-SFGetF ile Use std file dialog 
ayD1gHook 
Sf begin Declare stack frame 
wordresult myDlgResult Function result 
word mySF Item Which item was hit? 
long theDialog SFGetFile dialog ptr 
sfend That's all! 
enter Set up stack frame 
move .w mySF I tem, d? Get the item® 
cmp.w 8-1,00 Is this first time? 
bne NotF irst Go if not 
sub.1 8 14,sp Room for VAR parems 
move. | theDialog,-(sp) Stack DialogPtr 
move .w #get0pen,-(sp) Stack item * of "Open" 
pea 18(sp) VAR itemType 
pea 18(sp) VAR itemHandle 
pea 14(sp) VAR dispRect 
_GetDI tem Tell me about button 
movea. 1 8Csp2,o0 Get handle 
add. 1 #14, sp Drop data structure 
move. 1 að,-(sp) Stack item handle 
pea myTitle Pass title address 
-SetCTitle Make title = STR 
moveq 8-1,00 Мәке sure we're here 
NotF irst equ x 
cmp. w # 103, d Wes it "Select?" 
NotSelect Go if not 
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;*** This is where we will do all kinds of nifty magic *** 
рыны 


sub. 1 8 14, sp Room for VAR params 
move.] theDialog,-(sp) Stack DialogPtr 
move .W #7,-(5р) Stack File List item! 
pea  18(sp) VAR itemType 
реа 18Csp) VAR itemHandle 
реа 14Csp) VAR dispRect 
-GetDItem Tell me about File List 
с1г.1 -(sp) Room for pt 
pea (sp) Point to the point 
_GetMouse Here, mousie, mousie... 
pea 4(sp) Point to the rect 
-PtInRect Are we in File List? 
move.w # 103, dd Just to make sure 
move .b Csp)+,d1 Get answer 
add. 1 812,5р Drop remaining data 
bne.s NotSe lect If in File List, leave 
move .W 81,00 Treat like file open 
NotSelect equ x 
move .w dð, myDlgResult Store function result 
exit Exit the function 
4 
ayF ileFilter equ x 
loc New locals here; needed for McAssembly 


2 


11 


sfbegin Stack Frame Begin 


wordresult  myFilterResult À boolean 

long parmBlkPtr À pointer 

sfend Stack Frame End 
enter set up stack frame 
move .w 8-1, myFilterResult TRUE; 
exit Clean up and leave 


PromptString еди * 
text 8 "Highlight a folder and click /"Select/"" 


align 

agTitle equ x 
text ® "Select" title for "Open" button 
align 

myList equ x 
text "2299" Any old file type will do 
dcb.b 12,0 Remaining are nulls 


Now that I've given the code that does the trick, I should 
probably say a few words about how the replyRec looks when 
you ve opened a folder instead of a file. 

First of all, you can forget about the fName field. It won't 


be valid. Instead, vRefNum will contain the vRefNum of the 
folder, just like it does for a file, and - get this - fType will return 
the DirID of the folder ("Sorry about the type conflict," says 
Apple in the software supplement...obviously talking to Pascal 
programmers). Of course, the vRefNum and DirID are sufficient 
for all HFS OSTraps that deal with folders or files within a 
specific folder. Another thing that you can do if you want or need 
to is convert the vRefNum and DirID to a pathname extending 
from the root to the folder (or more precisely, from the folder to 
the root). One implementation of that algorithm appeared in 
MacTutor's special HFS issue (January '86). It was written in C 
by Mike Schuster. Translating it to the language of the reader's 
choice is an exercise left to the reader (the assembler version is 
actually rather simple). 

That just about covers it. Feel free to use the Not-So- 
Standard File dialog anytime you have a reason to want to select 
a folder instead of a file! 
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The Electrical Mac 


At the beginning of the summer, I decided to build my own 
Small Computer System Interface (SCSI) hard disk. I spent a 
month learning all I could about what made a hard disk fast and 
reliable. Then I ordered the parts and assembled it. It took me an 
additional three months of writing and debugging the software to 
make it work. I am writing this article so that you can learn from 
my experience and build your own hard disk. In the following 
pages, you'll find all the information that you will need to buy the 
parts and assemble a SCSI hard disk. My article in next months 
issue of MacTutor™ will describe a program for formatting your 


Tim Standing is a biochemist at the University of 
California, San Francisco, studying the three 
dimensional structure of proteins using x-ray 
diffraction. At work he uses Fortran and VAX 

assembly language on a Floating Point Systems 264 
computer. For the Mac, he uses MPW assembly and 


hard disk. 

Since I knew next to nothing about electronics, the idea of 
building my own hard disk seemed foolhardy at first. However, 
I did know quite a bit about programming and thought that I could 
write the necessary software. I had installed a couple of hard 
disks in IBM PC's and knew that there was nothing to it but 
correctly connecting up the cables. I figured that assembling a 
hard disk for my Mac was probably just as easy and that I could 
put one together without understanding how any of those funny 
looking chips worked. I was right, I still don't know how any of 
them work. If you've made a few cables before, you too should 
be able to make yourself a hard disk. You should expect to spend 
about the same amount of time as I did assembling all the parts 
(about 6 hours). 

This article is divided into two parts. First, I tell you what 
you need to know about controller boards and disk drives. Then, 
I give step-by-step instructions on assembly including a list of 
parts and suppliers. 


Understanding Hard Disks 
The SCSI interface is a standard way of communicating 
between microcomputers and peripherals (such as hard disks). 


The communication between the microcomputer and the periph- 
eral is made using a parallel interface. A parallel interface sends 
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each data byte (eight bits) down eight wires simultaneously, one 
for each bit. This is much faster than the other type of commu- 
nication, serial, where all eight bits are sent down the same wire 
one after another. In addition, SCSI communication uses a bus. 
This means that all the devices are connected one together in a 
line, with the Mac at one end. When the Mac wants to talk to a 
hard disk on the bus, it first sends the hard disk's number (called 
an address) down the bus to see if the hard disk is there. Each 
device on the bus must therefore have a unique address so that 
two devices won't respond to the same command. 

Your SCSI hard disk will be made of three parts: a disk 
drive, a controller board and a box with a power supply. The 
function of the box and power supply is to protect the electronics 
and to provide the necessary power. The disk drive itself stores 
the information that you write to it. So what does the controller 
board do? The controller board acts as an interpreter. It can 
determine which of the commands that come down the SCSI bus 
are addressed to it and can understand what the Mac wants it to 
do. It then translates these commands into something that the 
disk drive can understand. It tells the disk drive where to read and 
write from. Italsochecks the data for errors. If it finds one, itasks 
the disk drive to repeat the operation. Error-checking and 
correction is goes on independently without the Mac knowing it. 


Choice of Disk Drive 


I recommend a ST225 (20 Megabyte) disk drive from 
Seagate or one of the ST4000 series (also from Seagate). I've 
seen the ST225 advertised from a mail order house for as little as 
$329 (California Digital, 17700 Figueroa St., Carson, CA 90248; 
(213) 217-0500). The ST4000 series comes in several sizes 
ranging from 20 megabytes ($500) up to 90 megabytes ($1100) 
and is available from Mini Micro Supplies (see parts list for 
address and phone number). 

I recommend that you buy a disk drive from Seagate 
because they have a good track record. Although they don't have 
thelowest prices, they do make good disk drives and stand behind 
them. If you have problems with your disk drive (like it makes 
awhining noise when you start it up or doesn't start at all), double- 
check everything to make sure that it's hooked up correctly. If it 
still doesn't work, call the technical support folks at the place you 
purchased it and explain the problem. Even the best disk drive 
manufactures have a 1 - 2 % failure rate mostly because the disk 
drives get dropped during shipping. [Note: This rate varies 
depending on who you talk to. Usually, once you geta good drive, 
it will remain a good drive. This applies to commercially as- 
sembled drives as well. -Ed] 


13 


Fig. 1 Adaptec ACB 4000A Controler Board 


(Component Side) 


Red LED 


RP3 (To Be Removed) 


J4 RS 
Connects E: 
to SCSI Е 
Bus 


J5 (For SCSI Address) 


All disk drives are not created equal. There are five things 
you should know about the disk drive you are thinking of buying. 
The first and most important is its formatted size. Disk drives 
range in formatted size from twenty megabytes up to several 
hundred megabytes. The size you choose depends on your needs 
and how much you want to spend. 

The second thing you need to know about a disk drive is 
whether or not it is certified for Run Length Limited (RLL) 
encoding. By reading and writing at a higher density, RLL 
encoding allows you to get 50% more data on a given disk drive. 
Not all disk drives can operate at this higher density without 
making errors. RLL encoding also requires a special controller 
board. If you try to usean RLL controller board with a disk drive 
that is not certified for use with RLL, it may not work. I tried 
hooking up an RLL controller board to a Seagate ST 4051 disk 
drive (non-RLL certified) with no luck. 

You should also know whether your disk drive automati- 
cally “parks its heads" when the power is tumed off. “Parking the 
heads" means that the heads get locked in a special position when 
the disk drive is not being used so that they don't bounce around 
scratching the surface of the disk. This is especially important if 
you plan to carry your hard disk around a lot. Many disk drives 
require a specific command to park the heads. If the disk drive 
you use requires a specific command make sure the software you 
use includes it. 


The fourth thing that you should find out is how the disk 
drive moves the heads across the disk. There are two ways of 
doing it. One is to use a stepper motor, like that found in the 
floppy disk drives on your Mac. Like the floppy drives, these are 
slow. The speed of a disk drive is measured by its average access 
time which is the time needed for the head to move 1/3 of the way 
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across the disk. All disk drives which use stepper motors have 
average access times of between 65 and 90 milliseconds. 

The other method of moving the heads across the disk is to 
use a voice coil. This is similar to the voice coil on a stereo 
speaker. These are much faster and also more expensive. The 
average access time for this type of disk drive ranges from 25 - 

35 milliseconds. Usually these drives automatically park the 
heads when you turn off the power. 

The average access time will not affect how fast it takes you 
to read a file or start a program when the hard disk is new, but it 
will after you've been using it for a while. This is because a 
relatively empty hard disk stores files in sectors (512 bytes each) 
that are next to each other. Reading a file on a hard disk like this 
does not require the head to move much. After the hard disk fills 
up, files end up with each sector located on a different part of the 
disk. Now the head must move a lot to read the file. Any 
operation that requires you to read a small file won't be affected 
by average access time (e.g. starting an application or reading a 
MacWrite document). However, operations that read many files 
or read large files are heavily influenced by the average access 
time of the disk drive. These types of operations include 
compiling, using a database, returning to the Finder, or opening 
a folder. 

Finally, you need to find out how fast your disk drive will 
accept step pulses. A single step pulse tells the head to move one 
track over. The faster you can issue a step pulse, the faster the 
head will find the track that it is looking for. The interval between 
step pulses is called the step pulse timing. The step pulse timing 
has more of an affect for disk drives that use voice coils than for 
those that use stepper motors. When you purchase your disk 
drive, make sure that you find out what rate it will accept step 
pulses. The choices that you have using the controller card that 


© The Essential MacTutor, Vol. 3 


I recommend are 3 milliseconds, 28 microseconds or 12 micro- 
seconds. 

Older disk drives need 3 milliseconds between each step 
pulse. This is because they cannot count step pulses while the 
head is moving and have to wait for the head to reach the new 
track before they can accept the next pulse. A few years ago, disk 
drives became available that accept step pulses at 35 microsec- 
ond intervals. Step pulses issued at this speed require the disk 
drive to continue accepting and remembering step pulses while 
the head is still moving. Each step pulse is stored in a buffer; this 
is called buffered seeking. IBM adopted a step pulse timing of 
35 microseconds for its PC AT computers. This is considered 
slow by current standards. Most disk drives that you can buy 
today will accept step pulses at 12 microsecond intervals This is 
true of all the new Seagate disk drives. 


Choice of Controller Board 


There are at least three controller boards on the market that 
will work on a SCSIbus. The one that Ichose is made by Adaptec 
(model number ACB-4000A). It can control one or two disk 
drives and has many features that make it reliable and easy to use. 
Adaptec also makes a RLL version of this board called the ACB- 
4070. I know that the formatting program that I have written 
works with the ACB-4000A controller board, but I don't know if 
it will work with controller boards from other manufacturers. 

The Adaptec controller board allows you to use any inter- 
leave from 1 to 16 (if you don't know what interleave is, you 
should skip ahead and read the section entitled “What is Inter- 
leave"). The driver that I have written performs best with an 
interleave of 3. 


Choice of Box and Power Supply 


Most of the boxes which you've seen advertised in the back 
pages of IBM PC magazines will work for this project. You need 
to decide whether you want room for one or two disk drives. I 
bought a box for just one disk drive. It is an ugly grey color and 
even looks sort of like an IBM PC. I wrote “ТВМ sucks" across 
the front of the box just so my Mac wouldn't think that it was 
about to be replaced. 

When you buy a box, get one with a power supply. Make 
sure that you geta switching power supply as these are less prone 
to interference from your refrigerator or your landlord's vacuum 
cleaner. А switching power supply uses a sophisticated high 
frequency circuit rather than large capacitors to regulate output 
voltage. Asaresult, they are smaller, lighter, and create less heat. 


What is Interleave 
The interleave factor describes how many sectors on a track 
are skipped before reading the next one. This number is tuned to 


the speed of your software. If your software can't keep up with 
the disk drive operating with a given interleave, reading and 
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writing will actually go slower. The smaller the number the faster 
youcan read and write information. An interleave of 1 means that 
you read each sector in the order that it occurs on the track. An 
interleave of 2 means that you read one sector, skip one sector. 
An interleave of 3 means that you read one, skip 2, read one, skip 
2, etc. By skipping two sectors, you give the Mac time to catch 
up with the incoming data. 

In order to use a smaller interleave number you must have 
faster software. The driver that I have written works best using 
an interleave of 3. This limitation comes from the way that the 
SCSI manager was written by Apple. If I have the time this 
winter, I'ld like to rewrite the SCSI manager to make transfers 
faster. Taking advantage of this will require reformatting your 
disk with a smaller interleave number. 


Read Precompensation and 
Write Current Reduction 


As the head moves towards the center of the disk, data are 
written closer together. The exact method of reading and writing 
has to be altered slightly to compensate for this higher density. 
The Read Precompensation number and the Write Current 
Reduction number determines the first cylinder which requires 
these different read and write signals. You will need these two 
numbers in order to correctly low level format your hard disk. 

When you buy your disk drive, make sure that you find out 
what values to use for Read Precompensation and the Write 
Current Reduction. For a Seagate ST225, the Read Precompen- 
sation is 300. The Write Current Reduction is calculated by the 
disk drive itself, so you should use a value of 0. For the Seagate 
ST4000 series of disk drives, both of these numbers are calcu- 
lated by the disk drive, so you should set both of them to O. If you 
buy a Seagate disk drive and don't know what values to use, you 
can call Seagate Technical Support at (408) 438-5333. 


Static Electricity 


The chips used on the disk drive and controller board are 
very sensitive to static electricity. These chips contain very small 
transistors that can easily be burned out by small sparks. There- 
fore, both your controller board and disk drive will arrive in static 
shielding bags with huge warning labels all over them. If you are 
like me, you'll be totally intimidated by these labels and afraid to 
open the bags and take things out. Here's what you have to be 
careful with to avoid frying any of these chips. 

Leave everything in its bag until you are ready to use it. This 
will protect the parts from all sources of static electricity. When 
you're ready, spread out some aluminum foil and place the parts 
on the foil. Touch only the sides of the controller board and the 
metal frame of the disk drive when handling them. Avoid 
touching the components or any metal on the controller board or 
the disk drive board (this includes the connectors). If you must 
touch the components or connectors to plug in a cable, you should 
first touch both hands to the foil and then to the metal frame of the 
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diskdrive. By doing this immediately before you touch any static 
sensitive parts, you will discharge all the static electricity that has 
builtup on your hands. If you have to service your hard disk after 
you've put it all together, you should observe the same precau- 
tions. If you follow these simple rules, you shouldn't have any 
problems. 


Termination 


What is termination and what do you need to know about it? 
Termination is a method of reducing noise caused by signals 
bouncing off the ends of the wires. This type of noise is a problem 
on any high frequency data bus like a SCSI bus. It is called 
termination simply because it is something that is done to both 
ends of the bus. Termination is accomplished by taking resistors 
and placing them on all of the data wires. Two resistors are used 
for each of the eight data lines. One of these resistors goes 
between the data wire and ground, and the other goes between the 
data wire and + 5 volts. 

Although Apple should include termination inside the Mac 
Plus, they don't. They tell you that only the device closest to the 
Mac and the device furthest away from the Mac should be 
terminated. If you only have one device (excluding the Mac), 
then you only need one terminator. If you have two or more 
devices you will need two terminators. Terminators can be 
bought from your local Apple dealer (Apple part number 
M2559). 


Assembly Instructions 
As I said in the beginning, it took me 6 hours to put all the 


hardware together. If you have assembled everything correctly, 
it will take no more than 30 minutes to do the formatting. 


Tools Needed 

Tool: What you need it for: 
Regular Screwdriver Putting the parts together 
Philips Screwdriver 
Soldering Iron There are only 12 wires that need 
soldering. 
Pliers For attaching connectors to 
ribbon cable. 
File, Hacksaw, Drill For adding new slots for connec- 
tors on the back panel of 

the box that you use. 
Volt Ohm Meter To check that cables are made 
correctly. 
Magic Marker 
Heat Shrink Tubing 

Parts List 
16 


1 
1 


Adaptec, ACB-4000A 
Seagate, ST 4051 


Adaptec controller board. 
Hard disk drive (see the 


or ST 225 disk drive above section for 
suggestions). 

1  Boxwith power supply 

1 Apple, M2559 SCSI cable terminator. 

1 Apple, M2556 SCSI System Cable. This 


1 


connects your Mac to the 
DIP switch 

switch. You will mount 
use it for setting the SCSI 


8 feet 


1 


1 


AMP Female connector 
ground on the frame of the 
Spade Connector 

to the chassis ground. 


hard disk. 

Buy a three station DIP 
this on the back panel and 
address of your disk drive. 

50 pin Ribbon cable 

This is attached to the 
disk drive. 

To attach the ground wire 


1  20pin IDE connector Edge connector for the 
disk drive. 

2 34ріп IDE connector Edge connector for 

connecting the controller board to the disk drive. 


1 


50 pin IDC connector 
attach to the controller 


Female pin connector to 
board. 


2 20pin IDC connector Female pin connectors. 
One is used for the connection between the 
controller board and the disk drive. The other is 
used to connect the disk drive address lines to the 
DIP switch mounted onthe back panel. 

2 Amphenol, #57F-50 50 pin SCSI connector. 
These are connectors for the back panel and include 
latches. 

1 foot Heat shrink tubing 


1 


1 1/4 inch fuse holder 


termination power. 


1 


1 1/4 inch fuse 
for termination power. 


For back panel for 


500 milliamp, 250 volt fuse 


4 6X 32 X 1/2 inch screws They are used for mounting 
the controller board to the frame of the disk drive. 

4 6X 32 X 3/4 inch screws For mounting the SCSI 
connectors to the back panel. 

4 6X32 nuts Also for mounting SCSI 
connectors. 

8  Splined lock washers For mounting SCSI 
connectors. 

4 1/4 inch standoffs. Used for mounting the 
controller board to the frame of the disk drive. 

8 Nylon washers These are to prevent your 


screws or standoffs from 


components on the board. 


grounding any of the 


Where to Get Parts 


I purchased the controller board from Wyle Laboratories 
(408) 727-2500. Their price for the Adaptec ACB-4000A is 
$139. They have good service and great prices. 

The box with power with supply and the Seagate disk drive 
(model # ST4051) were both purchased from Mini-Micro Supply 
Inc., 1977 O'Toole Ave. Suite B108, San Jose, CA 95131, (408) 
435-1977. They charged me $120 for the enclosure (item # 
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E001-P) and $650 for the disk drive. The disk drive may seem 
expensive until you realize it is 43 megabytes and has 40 
millisecond average access time. 

The two SCSI connectors for the back panel (Amphenol 
#57F-50) were ordered from Cetec (408) 748-8550 and were $14 
each. 

All the other electrical supplies I purchased from Zack's 
Electronics at 1444 Market St. in San Francisco (415) 626-1444. 
You could probably go to any electronics supply house and get 
them or order them from Cetec when you order the other 
connectors. All of the parts listed above cost me just under $50. 

The Apple parts I bought from my local Apple dealer. The 
screws and nylon washers I bought from my local hardware store. 


Before You Start 


Itis a good idea to wait to buy all the connectors and cables 
that youneed until you have already received the controller board 
and the disk drive. That way you can see exactly what types of 
connectors you need. 

Look over all the board and the disk drive and make sure that 
you can recognize all of the connectors that I have illustrated in 
the diagrams (see fig. #1 ). Notice that all the connectors are 
labelled as to which is pin 41. You will find the pin numbers on 
both male and female connectors molded into the plastic of the 
connector itself. It may take a while to find them as they are often 
less than 1/16 of an inch high. In addition, the pin numbers are 
written in white on the boards to which the connectors are 
attached. I have shown where pin #1 is for each connector in all 
my figures. In addition, the IDC and IDE connectors also have 
a triangle on the side nearest pin #1. I usually mark this with a 
black magic marker when І make up the cables so that сап easily 
keep track of pin #1 at each end of the cable. 

None of the connectors used to connect to ribbon cable 
require soldering. They are pressed together with the cable 
between the two halves. You will need a pair of pliers or a small 
vice to apply enough pressure to get the two halves to mate 
properly. If you have never used this type of connector before, 
you should use a volt ohm meter to check that you've gotten good 
connections at both ends. If you make a mistake with one of the 
connectors, do not take it apart and reuse it. These connectors are 
not designed to be reused and will not make a good connection 
a second time. 

The ribbon cable has a red stripe down one side to help you 
attach connectors correctly. Always attach the connectors to the 
ribbon cable so that the red wire is pin #1. Assembling the cables 
carefully and checking them with a volt ohm meter will pay off 
in the long run. This is where 90% of my problems came from. 

In addition to 50 wire ribbon cable, you will need 34 wire, 
20 wire and 6 wire ribbon cable. Rather than buying four 
different sizes, you can take a length of the 50 wire ribbon cable 

and cut it between two wires with a razor blade to get the desired 
width you need. When you do this, be careful not to expose any 
of the wires by cutting through the insulation. 
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Original 
Connector 


Power Supply 


Socket for 
110 Volt AC 


Fan 
Fig 2a Original Back Panel 


Remove this 
with a file or 
hack saw 


Fig 2b Metal to be Removed 


2 SCSI 
Connectors 


110 Volt AC 


Fan Fuse for Termination Power 
Fig 2c Back Panel After Modification 


Step By Step Instructions 


1). Remove the fan, the power switch, the power supply, the 
fuse holder and all of the connectors from the box. Mark all wires 
and screws as you take them off so that you can be sure to replace 
them correctly. 

2). Now you need to add several holes to the back panel of 
your box (see fig. 2). They will be used for mounting the two 
SCSI connectors, the extra fuse holder and the DIP switch. The 
fuse holder you are adding is used for the +5 volt power that is 
needed for terminating the SCSI bus. The three station DIP 
switch is used for setting the SCSI address of your hard disk. You 
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will set it as a three digit binary number using these switches. 
Don't set your disk to number 7 as this is the number that your 
Mac uses. 

Start by making an opening for the two SCSI connectors. 
The center to center distance between these two connectors must 
be at least 3/4 of an inch. This is because the cables that Apple 
sells for the SCSI bus all come with rubber hoods and require 
extra clearance. (Before you start, remember that you still have 
to be able to mount the fan on the back panel.) I used a hack saw 
and a couple of files to make this opening. You must also drill 
and shape holes for the extra fuse holder and for the DIP switch. 
Modifying the back panel is the hardest part of constructing a 
SCSI hard disk and will take you the most time. It took me about 
3 hours to do. 

3). Replace the power switch, the power supply, the fan, the 
110 volt AC socket and fuse for the 110 volt AC input power. 
Attach the extra fuse holder to the back panel. Make sure that 
both of the metal tabs point up so that you can more easily solder 
wires to them. 

4). Remove the controller board from its protective bag. 
You will see two resistor packs that are mounted in sockets. They 
are labelled RP3 and RP4 on the board (I have labelled the same 
in fig. 1). They are usually red or yellow and have ten pins all in 
a straight line. Carefully remove both of these resistor packs 
using a pair of pliers. Be careful not to damage the controller 
board. You can throw both of the resistor packs away. 

5). Mount the controller board on the frame of the disk 
drive. There are threaded holes on the frame of all 5 1/4 inch 
diameter drives for this purpose. (If your disk drive does nothave 
mounting holes for the controller board, drill four holes in the 
base of the box and mount your controller board directly on the 
box.) The board should be mounted so that the component side 
faces away from the disk drive. This will give youroom to mount 
connectors at J4 and J5 (fig. 1). In addition, the red LED on the 
controller board should be at the same end as the red LED on the 
disk drive. This places the 20 pin and 34 pin connectors on both 
the controller board and the disk drive next to each other. 

Use the 6 x 32 x 1/2 inch screws to mount the controller 
board to the disk drive. The 1/4 inch standoffs (those little metal 
cylinders) will be put between the controller board and the disk 
drive and will provide an air space for cooling. Put a nylon 
washer on either side of the controller board to insulate it from the 
screw head and the standoff. This prevents the controller board 
from shorting out. 

6). Remove the mounting rails from the box if you haven't 
already done so. The mounting rails are the two pieces of sheet 
metal that are attached to the base of the box. They are designed 
to be attached to your disk drive, and will hold it in place. Attach 
the disk drive/controller board assembly to the mounting rails. 
There are screw holes in the frame of your disk drive for this 
purpose. When you mount the disk drive, the controller board 
should be facing the base of the box. There should be at least a 
3/4 inch clearance between the controller board and the base of 
the box so that you can plug in the connectors at J4 and J5 (fig. 
1). You may have to drill new holes in the mounting rails to 
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provide this clearance. 

7). Make a 6 inch piece of 34 wire ribbon cable from the 50 
wire ribbon cable that you bought. Attach one 34 pin edge 
connector to each end. Make sure that pin #1 of the first 
connector is connected to pin #1 of the second connector. Attach 
one end to the 34 pin edge on the controller board at J2 and the 
other to the 34 pin edge of the disk drive. Make sure that the two 
connectors are correctly oriented with respect to the boards. Each 
male edge connector has a notch between pin #4 and pin #6. Use 
these notches to help you attach the connectors correctly. 

8). Make a 6 inch piece of 20 wire ribbon cable. Attach one 
of the 20 pin female connectors to one end and the 20 pin edge 
connector to the other end. Check that pin #1 of the edge 
connector is connected to pin #1 of the female connector. Attach 
the 20 pin edge connector to the disk drive. Again make sure that 
you have it in the right orientation so that pin #1 is at the end 
which is notched. Join the 20 pin female connecter to the 20 pin 
male connecter on the controller board which is marked JO (see 
fig. 1). The male connector is marked in white lettering on the 
controller board itself. 

9). Now take a look at the remaining 20 pin male connector 
on the disk drive. It should have one jumper on it connecting a 
pair of pins which are next to each other. Make sure that it 
connects the pair of pins that are nearest the 20 pin edge 
connector. This sets the drive's address for the controller. The 
controller can only communicate with the disk drive when the 
disk drive is labelled with the lowest possible number. 

10). Make a 2 foot long 6 wire ribbon cable. Connect one 
end of this cable to the last remaining 20 pin female connector. 
The six wires should be connected to the sockets numbered 1 - 6 
on the female connecter. Separate the six wires for 1/2 inch at the 
other end and strip 1/4 inch of insulation from each one. Solder 
wires 1 and 2 to the first switch on the DIP switch. Solder wires 
3 and 4 to the second switch and the last two wires to the last 
switch. Now check that closing switch numberone connects pins 
#1 and #2 on the female 20 pin connecter. Close switch number 
two and check that it connects pins #3 and #4. The third switch 
should connect pins #5 and #6. 

11). Epoxy the DIP switch into the hole that you cut for it 
in the back panel. Connect the 20 pin female connector to the 
controller board at the 16 pin male connector labeled J5 (see fig. 
1). Make sure that the socket is installed with pin #1 of the female 
connector attached to pin A of the male connector (labelled in 
white lettering on the board itself). You will notice that the male 
connector on the board has only 16 pins and that your female 
connector has 20 pins. This is okay, the extra4 pins simply aren't 
used. 

12). Cut a 2 foot piece of 50 wire ribbon cable. Attach the 
50 pin female connector to one end. Connect one of the SCSI 
connectors to the other end. Again make sure that pin #1 from one 
connector is connected to pin #1 of the second. You will find that 
the SCSI connector is labelled with tiny numbers. These num- 
bers are on the outside which is the side with the latches. The 
SCSI connector and the 50 pin female connector use different 
numbering schemes. (Only pin #1 on the SCSI connector will 
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be connected to the same pin number on the 50 pin female 
connector. Pin 42 of the 50 pin female connector will be 
connected to pin #26 on the SCSI connector, etc.) 

Measure 3 inches up the cable from where you installed the 
first SCSIconnector and mount the second one here. Again make 
sure that pin #1 of this connector is connected with pin 41 of the 
other two connectors. 

13). You must now wire the SCSI connectors on the back 
panel to provide termination power (*5 volts). Measure up 4 
inches from this second SCSI connector and mark it with a magic 
marker. Now count over from the red wire (wire #1) and find the 
wire #26. Usearazor blade to cut between wire #26 and #27 from 
this point back to the second SCSI connector. Make sure that you 
don't cut through to the wire #26 or #27. You are only cutting the 
insulation between them. You should now have a 3 inch slit in 
the ribbon cable. Repeat this operation to separate wire 4/25 and 
#26. Now cutthe wire #26 as far away from the SCSI connector 
as you can, about 4 inches. Strip 1/4 inch of insulation from it. 
Cut a 6 inch piece of wire and strip 1/4 inch of insulation from 
each end. Solder this piece of wire to the separated wire from the 
50 wire ribbon cable and cover the joint with a length of heat 
shrink tubing. Connect the other end of the 6 inch wire to one of 
the metal tabs on the extra fuse holder (the one that you installed). 

14). Now you must connect the fuse holder to the +5 volt 
line from your power supply. Identify which of the wires coming 
from your power supply is the +5 volt line. It will be pin #4 on 
one of the white plastic connectors that plug into the disk drive 
and the controller board. Mark it with a piece of tape. Cuta9 inch 
piece of wire and strip 1/4 inch of insulation from each end. 
Solder one end of this wire to the unused metal tab of the fuse 
holder. Solder the other end of the 9 inch wire to the +5 volt line. 
The easiest way to do this is to cut the +5 volt line in the middle 
and strip the insulation from each end. Then solder the two ends 
of the +5 volt line together with the 9 inch wire from the fuse 
holder. Be sure to put a piece of heat shrink tubing on one of the 
wires before you solder them so that you can cover the joint when 
you are done. 

15). Install a 500 milliamp 1 1/4 inch fuse into the fuse 
holder that you added to the back panel. 

16). Connect the two SCSI connectors to the back panel. 
Use toothed washers between the back panel and the connectors 
to ensure that the connectors are properly grounded. 
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17). Plug the 50 pin female connector into the controller 
board at J4 (see fig. 1). You should check the connection to make 
sure that pin #1 of the male connector is attached to pin #1 of the 
female. The pin numbers for the male connector are marked in 
white lettering on the board. 

18). Attach both power connectors, one to the disk drive and 
one to the controller board (see fig. 1). These connectors are 
made of white plastic and have four pins arranged ina line. The 
male connector has a ridge on it to ensure that it is properly 
inserted. 

19). Cut a one foot piece of wire and attach the female АМР 
connector to one end. Solder the spade connector to the other end. 
Attach the AMP connector to the ground tab on the disk drive 
frame. The ground tab is located next to the 20 pin and 34 pin 
connectors on the disk drive. Attach the spade connector to the 
chassis ground where the power supply is grounded. 

20). Screw the rails into the base of the box. 

21). Replace the cover to the box. 

22). Make sure that both your Mac and your hard disk are 
turned off. Connect the Mac to one of the SCSI connectors on the 
back of your hard disk. Connect a terminator to the other one. 

23). Cross your fingers. [MacTutor is not responsible for 
anything that happens at this point! -Ed] 

24). Turn on your hard disk (the Mac should still be turned 
off). You should hear the disk drive spin up. While it is starting 
up the red light on the controler card should be on. It should go 
off when the disk reaches the correct speed. If it starts blinking, 
or the drive does not start spinning you have not connected the 
drive to the controller board correctly. 

25). Now turn on your Mac. You should see the LED on the 
controller board blinking at 1 second intervals. The Mac will not 
boot correctly because the hard disk is not formatted. The 
blinking LED on the controller card tells you that the controller 
card is correctly connected to the Mac. If it does not blink, you 
have either incorrectly wired the Mac, or you have incorrect 
termination. You may have forgotten to remove the terminator 
packs from the controller board or don't have a terminator 
attached to one of the SCSI connectors on your hard disk). 


Neat Time: The Formatting Program! рм Я 


SP. 
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Tech Notes 
Goodby Kiss by Dan Weston 
MacTutor Vol. 3 No. 2 


I'd like to inform the Mac community of a bug in the generic 
desk accessories that appear in my book, The Complete Book of 
Macintosh Assembly Language Programming, Vol I. Kirk 
Austin pointed out to me that the desk accessories crashed when 
receiving a goodbye kiss. The goodbye kiss is supposed to let 
your desk accessory clean up after itself if the application over 
which the accessory is running is terminated. For example, if 
your DA maintained open disk files or messed with low memory 
globals, you would normally close the files and reset the globals 
when a user closed the desk accessory. The goodbye kiss is 
provided by the Mac system software for those cases where the 
user quits an application without first closing the desk accesso- 
ries. The underlying application doesn't need to be concerned 
with the goodbye kiss; it is handled totally by the Mac system 
software as it reinitializes the heap for the next program. 

If you want your desk accessory to receive the goodbye kiss 
you must set bit #12 of the first word in the DA header. When an 
application terminates, the system software looks at each open 
desk accessory and sends a goodbye kiss if the appropriate bit is 
set in the DA header. 

The goodbye kiss is a good idea. It prevents your desk 
accessory from being blown away without warning. The prob- 
lem is that Inside Macintosh doesn't document how the goodbye 
kiss is implemented. In my book, I said that the goodbye kiss 
invoked the desk accessory's close routine. Now, after investi- 
gating a little further as a result of Kirk's letter, I find that the 
goodbye kiss doesn't invoke the close routine. Instead, the 
goodbye kiss is a control call with CSCode = -1. This causes big 
problems for my DA code because I use a jump table based on the 
belief that CSCode will ALWAYS be between 64 and 73. When 
the -1 CSCode hits the jump table it heads for ozone city; reach 
for the reset button. | 

The solution is to put a special case at the beginning of the 
control routine to watch for the goodbye control call and route 
it around the jump table (or just disable the goodbye call in the 
header, as Kirk did). 

The modified code section follows: 


Ф 
; Control handles the control messages, which are the heart 
; of the driver. Code values range from 64-73 (*** and -1 

; for goodbye kiss ***) enter with pointer to DCE in A1 
; end pointer to Paramblock in AQ 


Control 
MOVEM.L — A3-A4,-CSP) ; preserve АЗ - А4 
MOVE.L A1,A4 ; keep DCE ptr in M 
MOVE.L A8, АЗ ; keep Pblock ptr in A3 
MOVE.W CSCode(A3),DØ ; get control opCode Pblock 
АХА 
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CMP .Ұ8-1,00 ; is this the goodbye kiss? BEQ 


DoGoodbye ; goodbye routine 

гезе 

SUB . W 864,00 ; edjust renge to 0-9 
ADD .W 00,00 ; multiply by 2 for table 
MOVE.W — ControlTableCD22,00 ; offset to routineJMP 


Сопіго1Тәр1е(00) ; jump to it 

айра какы лауына Offset table for Control routines --------- 

; **almost** all possible control messages that can be sent to 
; а DA ere here. All the routines mentioned here should 

; return by branching to CtlDone. 


ControlTable: 


DC .W DoEvent-ControlTable 
DC.W DoPeriodic-Control Table 
DC.W DoCursor-Control Table 

W DoMenu-ControlTable 


; en event (64) 

; а periodic interupt (65) 

; adjust cursor on DA wind (66) 
DC. ; menu selection (67) 
DC.W DoUndo-ControlTable ; undo (68) 
DC.W Ct1Done-ControlTable ; *** code 69 is not used *** 
DC.W DoCut-ControlTable ^ 
DC.W ; 
DC .W À 
DC.W ; 


; cut (70) 
DoCopy-ControlTable ; copy (71) 
.W DoPeste-ControlTable ; peste (72) 
.W DoClear-ControlTable ; clear (73) 
CtlDone: 
MOVE.L A4,A1 ; return DCE ptr to Al 
MOVE.L АЗ,А0 ; return PBlock ptr to А0 
MOVEM.L (SP)+,A3-A4 ; АЗ - M restored 
MOVE .W 19 00 ; no error 
RTS ; go back to calling progrem 
;т--------------------------------------------------- 
DoGoodBye : 
MOVE.L — M,A ; return DCE ptr to A1 
MOVE.L АЗ,Аб ; return PBlock ptr to A0 
MOVEM.L СР 2+, АЗ-А4 ; АЗ - M restored 
MOVE .W #9 00 ; no error 
MOVE.L JI0Done,-CSP) ; return vector for asynch calis 
RTS ; go back to calling program 
BRA.S Ct 1Done 


One other detail that is important to note is that the goodbye 
kiss is an asynchronous control call. All other calls to desk 
accessories are synchronous, which means that they can return 
with a simple RTS. Asynchronous calls, on the other hand, must 
return via the JIODone routine. The low memery global JIO- 
Done, holds a pointer to this system routine, which clears the 
request from the I/O queue. We move this pointer onto the stack 
and then RTS. This routes our return through the JIODone 
routine. 

Thanks to Kirk for bringing this to my attention. If anyone 
else has bugs to report from the book I'd love to hear about them. 
AS best I can, I'll fix the bugs and post the information here in 
Mactutor. 


Have а Tech Note? Submit it to 
MacTutor and share it with others. 
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Assembly Language Lab 
Video Independence 


Working With Big Screens 


The big screens are here. You've seen them at MacExpo in 
Boston and elsewhere. Micrographix, E-machine, Radius; the 
names will soon be more familiar. And now the Macintosh II and 
custom third party video boards and monitors will soon dominate 
the Macintosh world. Will your applications run on the big 
screens? 

If you've already been testing your programs on the Lisa/ 
XL, then you probably already know how to work with other 
screen sizes. But most of us are poking along with a single Mac 
and we don't get a chance to play with the other members of the 
Macintosh family. 

It's really easy to make sure that your programs will take 
advantage of the big screens. This short article shows how find 
out how big the current screen is and how to grow and move your 
windows so that they can use the whole screen. 


How Big is the Screen? 


The first thing to do is check the Quickdraw globals for the 
screenbits.bounds rectangle which gives the bounding rectangle 
for the whole screen. Quickdraw and the window manager use 
this rectangle, so you might as well do it too. 

GetScreenSize is a short assembly language subroutine that 
takes a pointer to a rectangle variable and fills it in with the 
coordinates of screenbits.bounds. 


; GetScreenSize.ASM 

; This module finds out the size of the screen 

; currently installed on your Mac 

; It fills in а VAR rectangle with the coordinates 
; of screenbits.bounds 

INCLUDE QuickEqu.D 


XDEF GetScreenS ize 


; Procedure — GetScreenSize(VAR r:rect) 

GetScreenS ize: 

r SET 8 )Offset to rectangle parameter 
parambytes SET 4 ; bytes for parameter 

LINK A6, #8 ; по locals 

MOVE.L г(Аб),А1 ; get dest rect 

MOVE.L — GrefGlobals(A52),A0 ; get QD globals 

LEA screenBits*boundsCA2), Ad 

MOVE.L СА )+, СА1)+ ; move the first pert 
MOVE .L C(AQ2*, CA12* ; move the rest 
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Asm Link 
UNLK A6 ; get rid of stack frame 
MOVE.L (SP)*,A0 ; return address 
ADDA .W 8iperembytes,SP ; Strip parameter 
JMP САЙ) ; return 


GetScreenSize uses register A5 to get the pointer to the 
Quickdraw globals and then offsets into the globals to get at 
screenbits.bounds. Then it copies the coordinates into the VAR 
rectangle. If you are using a high level language, then you can 
probably use an expression like 


tempRect := screenbits.bounds; 
Dragging a Window all Over Town 


Once you have the screen dimensions (top and left of 
screenbits.bounds are always 0,0) you can use them to guide 
window dragging and growing. For instance, DragWindow 
takes a rectangle parameter that delimits the boundaries in which 
the window may be dragged. A good strategy is to inset our copy 
of screenbits.bounds by about 20 pixels so that at least part of the 
window will remain on the screen at all times. Figure 1 shows just 
how far we can drag a window within the inset screen rectangle. 
The code for doing this is shown below. 


; The click was in the drag bar of the window. Drag it. 


; XProcedure GetScreenSizeCVAR r:Rect) 

PEA tRectCA5) ; global scratch rect 
JSR Ge tScreenS ize 

;Procedure InsetRect(VAR r:Rect;dh, dv: INTEGER) 


tRect(A5) ; the rect 
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MOVE .W $20, -CSP) ; dh 
MOVE.W 120, -CSP) ; dv 
_InsetRect 


; DragWindow CtheWindow:WindowPtr; startPt: Point; 
boundsRect: Rect); 


MOVE.L WWindow(A52,-C(SP) ; Pass window 
MOVE.L PointCA52,-CSP); mouse coordinates 
РЕА tRectCAb) ; and boundaries 
-DregW indow ; Drag Window 
BRA Nex tEvent ; Go get next event 


Growing As Big as You Can 


Another use for the screen boundaries is to govern Grow- 
Window so that your windows can get as big as the biggest 
screen. GrowWindow takes a rectangle parameter; the top and 
left coordinates specify the smallest vertical and horizontal 
measurements the window can have. I choose 70 for each of 
these so that even the smallest window will have complete scoll 
bars, including a thumb, as shown in figure 2. 

€ File Edit 


Figure 2: GrowWindow limits 


The bottom and right coordinates of the growrect parameter 
to GrowWindow specify the maximum vertical and horizontal 
dimensions the window can have. The bottom coordinate of 
screenbits.bounds, minus about 15 pixels, is good for the maxi- 
mum height. The maximum width should be wider than the 
screen, however, to allow for stretching windows partially off the 
sides of the screen, as many people learned to do with MacWrite. 
I chose the largest positive integer, $7FFF, for my maximum 
width. Beware of using negative numbers for this parameter. 

Interestingly enough, even though MacWirite will let you 
make a window much wider than the screen, it seems to have the 
original Mac screen height hard-coded into its grow routine. E- 
Machines includes a nice ROM patch with its big screen that lets 
you hold down the option key while growing a window to 
override the limits that the underlying program may be trying to 
impose on window size. The code fragment to grow a window on 
an arbitrary screen is shown below. 


жашан кааран ннн оого “Sse ase RR 
DoGrow: 
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; first include scroll bar and grow region in update region 
BSR InvalidScrol | 


; here is where we actually grow the window 
; XProcedure GetScreenSizeCVAR r:Rect) 


PEA tRectCA5) ; global scratch rect 
JSR GetScreenSize 

ADD.W 870, tRectt+topCA5) ; 10 pixels high 

ADD. W #79, tRect+leftCA5) ; 70 pixels wide 

SUB .W 8 15, tRect+bottomCA5) ; not too tall 

MOVE . W S$7FFF, tRect+right(A5) — ;extra-wide OK 


;FUNCTION GrowWindowCtheWindow:WindowPtr;startPt:Point; 
; sizeRect :Rect) :LONGINT 
CLR.L 


-(SP) ; Space for result 
MOVE.L § WWindowCA5),-CSP) ; theWindow 
MOVE .L PointCA5),-CSP) ; star tPt 
PEA tRect(A5) ; SizeRect 
_GrowWindow 
MOVE .W CSP )+,01 ; New vertical dimension 
MOVE.W С5Р)+,00 ; new horizontal dimension 


; now draw it to the new size 
True Confessions 


It is really so easy to check the screen size that there is no 
excuse for not doing it. Iam sorry to say that I make the mistake 
of using hard-coded screen sizes in some of my example pro- 
grams in The Complete Book of Macintosh Assembly Langauge 
Programming, Vol I. We all live and learn, I guess. I am 
preparing a list of other things that could have been better in the 
book. Some suggestions have already come from readers. I 
encourage you to send me your comments so that I can keep the 
material up-to-date through articles like this or maybe with 
mailings to readers. [Dan Weston's two book series, The Com- 
plete Book of Macintosh Assembly Language Programming, 
Vol. 1 & 2, is aclassic and one of the best of all Mac programming 
books. We recommend it highly. Write to Dan care of MacTutor 
and we will forward any comments to him. His books are 
published by Scott Foresman & Co. and available at B. Dalton 
bookstores. -Ed] 


Big Screens Have Big Prices 
Anthony J. Oresteen 
Batavia, IL 

In recent months there have been numerous large screen 
monitors introduced for the Macintosh. These include the Ra- 
dius, Big Picture, MegaScreen П, ect. One thing in common with 
these productsis the big price. They all cost about $2000! Similar 
screens are available for the IBM PC world at half the price, 
around $999 for screen, PC card and support software. The Wyse 
WY-700 at 1200 x 800 is one that comes to mind. Somehow 1 
smell a snake here. What are Macintosh buyers getting for the 
extra $1000? Perhaps we can learn a lesson from "hard disk" 
history. I'm waiting for the price drop! 

[The impact of the Mac II will make alternate screen 
technologies more acceptable, driving up demand and competi- 
tion, which will drive down the price. -Ed] _ 

Сәмі 
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Advanced Mac'ing 
SCSI Formatter Project, Part II 


Where are we going 

This article is the second in a series on how to construct and 
format a SCSI hard disk. The first (MacTutor, February 1987) 
described in detail how to assemble a SCSI hard disk. This article 
describes a program called Format that performs the low level 
formatting of a SCSI hard disk. I have divided this article into 
three parts. In the first section, I cover some of the theory 
regarding the SCSI protocol. Included in this section is a 
description of how Apple's implementation of the protocol has 
made writing SCSI software much easier. The second section 
describes in detail how a SCSI command is sent to a SCSI hard 
disk and how data transfer is accomplished. I use U2 Formatter 
as an example. In the last section, I give step by step instructions 
on how to use this program including comments as to what may 
go wrong at each step and how to fix it. 

During low level formatting, the Macintosh sends informa- 
tion to the controller card describing the disk drive. This 
information includes both the physical characteristics (e.g. 
number or cylinders and number of heads) and the type of sectors 
that are to be used (sector size and interleaving). The controller 
card uses this information to write track markings on the disk 
surface so that information can be stored there. It also stores this 
information on a dedicated track on the disk surface so that it can 
be read into the controller card RAM when the power is turned 
on. Once the low level formatting has been completed, a program 
such as Apple's Generic SCSI Installer (available from Apple 
Software Support) can be used to construct a files system, install 
a driver and write the boot blocks. Although the drive can store 
information after low level formatting, it cannot be recognized as 
a volume by the Macintosh until a file system has been con- 
structed оп и. (A SCSI driver will be the subject ofa future article 
in this series) 

The program Format should work with any hard disk that 
uses the Adaptec ACB-4000A controller card or the Adaptec 
ACB-4070 which is their RLL controller card. In addition, it 
should work with any of the Seagate disk drives that have built 
in controllers. These drives all have an “М” at the end of the 
model number (e.g. “ST225N”). I have referred to the documen- 
tation for a Seagate ST225N while writing this program. 

I have developed this program using a 40 megabyte Seagate 
(ST4051) hard disk connected to an Adaptec ACB-4000A con- 
troller card. I have also tested it with a 155 megabyte CDC Wren 
III (see side bar article on the Wren drive.) It should work with 
other drives and controller cards, but Icannot guarantee it. There 
are subtle differences in the way different manufactures imple- 
ment the SCSI commands that make writing a universal format- 
ting program difficult. 

The Wren III is the fastest drive I have used on the Macintosh. 
Using the time needed to assemble and link the Format program 
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as a benchmark, the Wren III is more than 40% faster than a Data 
Frame XP-40. Disk Timer II rates the 155 Mbyte drive as 118 for 
write, 108 for read and 9 for access time with an interleave of 3:1. 
The average access time on the drive is 15 msec. That’s more 
than twice as fast as any other drive available for the Mac. In 
addition, the drive can transfer data at 1.25 Mbytes/second, 
which is as fast as the Mac II can read it in. The Wren III comes 
in three sizes: 86, 121, and 155 Mbytes which range in price from 
$1510 to $1710. They are available from Arrow Electronics 521 
Weddell Drive, Sunnyvale, CA 94089, (800-325-3329). 

The only problem with the Wren III is that the biege colored 
Macintosh Plus will not boot properly from them. If you buy a 
platinum Macintosh Plus, or get a copy of the ROMs from one, 
the Wren III will work fine. The EPROM’s you need to do this 
are 27C512, 150 nsec. They are made by Atmel and are available 
from Insight Electronics, San Diego, (619)-587-0471. (The 
ROMS in the platinum Mac Plus have a modified boot code that 
does a reset on power on and keeps polling until a hard disk 
responds. In the standard Mac Plus, they did a reset and poll in a 
loop of 1 second, which is shorter than the recovery tme of the 
Wren III to respond to a reset command. Hence, the Wren III will 
never come up! The new ROMS re-poll the driver when they get 
a drive not ready signal rather than resetting every second. This 
is not strict SCSI protocol and the people at CDC pointed this out 
to Apple, which then changed it’s ROMS. To get the ROMS, you 
needa friend in an Apple dealership whocan work with you since 
the dealers are notallowed to swap the ROMS unless you fry your 
board.) 

MPW 

Before I get into the details of SCSI commands, I will say a 
few things about MPW. I switched from the MDS system to 
MPW because I got tired of waiting for a good linker to show up 
for MDS. MPW is powerful and allows you to develop in 
PASCAL, C or assembly language and link the results together. 
More importantly, the MPW environment provides a lot of tools 
that make developmenteasier. In this section, I will describe both 
a modification that I have made to the “Make utility" to make it 
entirely automatic and a few bugs that I have found in the 
assembler that you should look out for. This program was 
developed using MPW version 1.0.1. Ihave included all the files 
that you will need for this project including the Makefile which 
establishes the dependency rules used for automatic assembly 
and linking. You will notice that the dependencies in the 
Makefile specify that the program is relinked anytime after the 
Rez tool is used. This is because Rez tends to trash the code 
resources in the program being built. 

I have modified the Make command so that it automatically 
executes its output. By doing this, you can build your application 
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by simply typing the command “Make”. The modification 
requires that you create a new folder inside the “MPW” folder 
called “Scratch”. The enclosed е “Маке” must then be placed 
in the “Tools” folder. Lastly, the line "Alias Make Makeit" must 
be placed in the UserStartup file. 

Although I have not uncovered any bugs in the linker, the 
MPW assembler does not always create the instruction that you 
specify! On three occasions it assembled instructions incor- 
rectly. In all three instances, I got the assembler to correctly 
assemble the instructions by either changing the instruction order 
or adding a label to the line above. If it looks like something 
funny is happening with your code, check that the executing code 
is what you think it is by using the disassemble feature in a 
debugger like TMON. Lets hope the 2.0 version will fix this bug 
as an assembler that lies is not much good for anything. 

Lastly, I use the “dump” assembly directive to load symbols 
into a е. You will see that all the files like “Traps.d” are loaded 
in at the beginning of each source file. To use this you must place 
the following lines: 

Dump ‘FileName .d’ 

end 
at the end of each of the files in the AIncludes folder and then 
assemble these files. This will create a file called “Filename.d” 
for each file which is a lot like the packed symbol files in MDS 
and will make your assembly runs a lot faster. 

SCSI Bus Phases 

There are seven different states that the SCSI bus can be in. 
These are called Bus Phases and are determined by which device 
has control of the bus and what information is being transfered on 
the bus. The bus phases that the SCSI bus goes through during 
a SCSI command are: arbitration, selection, command, data, 
status, message and lastly bus free. During the arbitration phase, 
the Mac (the initiator) tries to gain control of the bus. If it is 
successful, the initiator tries to select your hard disk (target 
device) during a phase called the selection phase. Once a target 
device has been selected, the target determines what information 
will be transferred down the bus and when. The target also 
determines which direction the information travels down the bus. 
The target device then requests a SCSI command from the 
initiator in the command phase. If the SCSI command that was 
transfered during the command phase indicated that there was 
data to be transferred between the target and the initiator, the bus 
will then enter the Dataphase. An example of this would be a read 
or write command where blocks of data are transfered down the 
bus. Once the target has transfered the number of bytes specified 
by the command, the bus enters the status phase. Here the target 
sends a single byte of information to the initiator. This status byte 
is an error code which describes any errors that may have 
occured. The status byte is cleared if the command was com- 
pleted successfully. The message phase is used to transfer 
additional information between the target and the initiator. The 
Adaptec ACB-4000A always sends a clear byte in the message 
phase which is the command complete message. I have therefore 
ignored the message byte in my program. At the end of the 
message phase, the target determines that there is no more 
information to transfer down the bus and disconnects from the 
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initiator. The bus then enters the Bus Free Phase where no device 
has control of the bus. 

During all of these phases, timing is critical. After each bus 
phase change, there is a required amount of time necessary to let 
the signal settle. There is also a maximum time delay after which 
the target device will time out. There are also timing specifica- 
tions for the arbitration phase that describe how long an initiator 
device should wait to determine if he has gained control of the 
bus. Apple decided to use the NCR 5380 chip to connect to the 
SCSIbus. This has several advantages including the fact that the 
chip performs many SCSI bus functions in hardware. It arbitrates 
for use of the bus, including performing retries, can select a 
target, send commands and transfer data. All of these actions are 
done in hardware. The timing is determined on the chip using a 
gate delay, rather than a clock pulse, which allows Apple to use 
the same chip in any computer regardless of the clock speed. (Of 
course, a vendor change or manufacturing quirk could change the 
average gate delay time, rendering some Macs less reliable than 
others.) 

This SCSI code is collectively known as the SCSI Manager 
and includes traps for all types of SCSI operations. The _SCSI- 
Get trap arbitrates for control of the SCSI bus. Тһе SCSISelect 
trap selects the target device. The  SCSICmd trap sends the 
command in the Command Phase. It includes a count for the size 
of the command which is either 6 or 10 bytes. The format and size 
of the various SCSI commands are described in the next section. 
Data is transfered by sending the correct SCSI read or write 
command using the SCSIcmd trap. The Mac must then be 
instructed to transfer the data using one of the SCSI read or write 
traps. These traps use a pseudo program that describes the 
number of bytes to be transfered and where they are to be 
transfered to or from. I will discuss pseudo programs in detail 
later. 

Lastly, the SCSIComplete trap instructs the Mac to wait for 
the target to complete the command. It includes the number of 
ticks to wait for completion and returns the status byte and 
message byte. I have found that the Status byte is often returned 
with a value of 2. This should signify that the drive was unable 
to finish seeking to the desired track. A status byte equal to 2 is 
returned even for commands which cannot return this error code, 
or for commands which completed successfully (status byte 
should equal 0). Accurate status byte reporting was obviously 
not a prioirty for the software engineer at Apple who wrote the 
SCSI manager! This bug is in the Mac Plus, but I haven’tchecked 
if it is still in the Platinum Mac Plus ROMS. Obviously, the Mac 
Plus ROMS have been changed considerably in the Platinum 
Macs and it is inexcusable that Apple does not at least offer the 
opportunity for Mac Plus owners to purchase new ROM sets. 

SCSI Commands 

SCSI commands are divided into two types: class 0 com- 
mands which are 6 bytes long and class 1 commands which are 
10 bytes long. The data structure that includes all the command 
information (6 or 10 bytes) is called a command descriptor block 
(CDB). SCSI commands often contain fields that are less than 1 
byte long. For example, bytes 0 and 1 of all SCSI commands 
contain four fields: the class code, the OP code, the logical unit 
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number (for devices that have more than one disk drive con- 
nected to a single controller card) and 5 bits of command specific 
information. The format of these four fields is the same for all 
SCSI commands used in this program. 

Some commands require more information than there is 
room for in the command descriptor block. In these commands, 
the command descriptor block includes a count byte which tells 
the SCSI hard disk how many bytes it should request from the 
Macintosh. The information is then transfered in the same way 
as in a read or write command, using a pseudo program and a 
_SCSIRead or __SCSIWrite trap. An example of this is the Mode 
Select command which is sent just prior to a Format Unit 
command, when formatting a SCSI hard disk. This information 
is included in a 24 byte parameter list and includes information 
such as write pre-compensation cylinder, reduced write current 
cylinder, cylinder count and head count. 

Pseudo Programs 

So what is this pseudo program and why not use a real 
program instead? The Pseudo program (Apple refers to them as 
Transfer Instruction Blocks) is a short subroutine of interpreted 
instructions. The ANSI standard for SCSI specifies the OP codes 
for pseudo instructions and the parameters used with them. Why 
were interpreted instructions specified? By specifying a set of 
OP codes for data transfer subroutines, the transfer functions can 
be performed by an I/O channel controller. This dedicated 
hardware would have these OP codes as its instruction set and 
would reduce the load on the CPU during I/O. This is important 
for multitasking systems. 

While Apple adheres to this part of the ANSI SCSI standard, 
they have not used hardware to perform the transfer instructions. 
Instead, all Macintoshs interpret these instructions. This adher- 
ence to the standard comes at a price; lower transfer speed. The 
alternative method of writing transfer subroutines is to use 
instructions that can be executed directly by the MC 68000. 
Some SCSI hard disk manufactures (e.g. Super Mac Technolo- 
gies and Micha) have used this method. This allows them to use 
a faster transfer rate and therefore use a smaller interleave. The 
driver in the Data Frame intializer version 2.1 uses a block of 256 
“move.b (АО) (А2)+” instructions for blind reads and a block of 
256 "move.b (А2)+,(А 1)” instructions for blind writes. Al- 
though this method of writing data routines is faster than that 
employed by Apple, it is very dependent on timing to work 
properly. Any change in the transfer rate of the drive or the CPU 
speed (e.g. asina Macintosh П) would cripple this technique, and 
require a modification by the manufacturer. 

The SCSI Manager section of IM volume IV includes a 
description of each of the pseudo instructions and their parame- 
ters. All instructions are 10 bytes long; a word for the pseudo 
instruction OP code followed by two long word parameters. For 
a read or write operation, we simply create a loop with a transfer 
instruction anda branch with a loop counter. I have heard that the 
code which interprets the SCSI pseudo instructions is not terribly 
robust, so it is better to not try and do anything too fancy with it. 

You will notice that the pseudo program that I have put in the 
WriteDisk routine could have been written with two instructions 
rather than the three that I used, by using the transfer byte count 
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as a parameter in the SCInc instruction. Instead, I placed 1 here 
and made a loop which transferes only 1 byte at a time. I did this 
solely to demonstrate how one constructs a loop in the pseudo 
program. | 
Examples of SCSI commands 

The simplest example of a SCSI command is found in the 
SelAddrProc procedure. Here I send a Test Unit Ready com- 
mand to see if the target device is ready. Ithen test the Statusbyte 
to see if the target device is connected and ready to be formatted. 

More complex examples of SCSI commands can be found in 
the FormatProc procedure. This procedure sends two commands 
including a Mode Select command which must be sent imedi- 
ately before formatting the disk. This command tells the control- 
lercard what type of hard disk is connected to itand how to format 
it. As I explain in the source code comments, the mode select 
command is followed by acall to WriteDisk which is a subroutine 
that writes to the hard disk using the _SCSI write trap and a 
pseudo program. I then use the Format Unit command to format 
the hard disk. This command includes the interleave value and 
is followed by data which describes where the disk media defects 
are found. 

A Few comments about error handling 

I have included in the error dialog box, not only the cause of 
the error but its most probable cause. This is not always the 
reason you got this error, but it is 90% of the time. I check for all 
the SCSI command errors that you are likely to get at any part of 
the program. If you are getting Phase errors, the most likely 
problem is that the timing loop in the ResetDisk procedure is too 
short. Try increasing the delay from 60 ticks to 120 or 180 ticks. 
This will give your controller more time to complete a reset. 
Selection errors are always cabling or termination problems. 

Step-by-Step 

1). Connect your hard disk to the Macintosh and turn both 
devices on. Make sure that the hard disk is correctly 
terminated and note what SCSI address it has. The drive’s 
address cannot be 7 as this is the address of the Macintosh. 
If you use DIP switches or jumpers to set the drive’s address, 
you are setting it in binary, with closed switches signifying 
1 and open switches signifying 0. The switch that closes the 
connection between pins A and B on the Adaptec ACB- 
4000A is the low bit on the SCSI Address. 

2). Open the Format program and choose Select Address from 
the SCSI menu. Choose the address that you have given the 
disk drive and then hit the select button. The program then 
goes and resets the SCSI bus and tries to select the device. 
(If it did work, you will not see an error message.) If you get 
a drive selection error, the drive is either the wrong address, 
is not correctly terminated or you have incorrectly attached 
one of the connectors on the ribbon cable. 

3). Next choose the Enter Parameters from the SCSI menu. 
Enter all the values for your drive. If your drive does not 
need a parameter, use the default value as this will send a0 
in this field and will work properly. The CDC Wren III only 
needs to be told which interleave to use, so this is the only 
thing you need to enter in this dialog box. If you are 
uncertain of which value to use for the step rate, use the 25 


25 


msec value. All but the most ancient drives will work 
correctly with this value. To determine which interleave to 
use, you must use trial and error. The value that is most 
likely the best is 3:1. To determine the correct value, you 
must format your drive using different interleave values. 
Then install a driver and copy a large file or folder onto the 
disk. I use a 1.2 Mbyte system file for this purpose. Now 
determine the amount of time it takes to duplicate the file. 
Do this with each interleave value. The value that gives you 
the shortest time for duplicating the file is the one you 
should use. 

4). Now choose Enter Defects from the SCSI menu. You can 
enter up to 60 defects. You should have received a list of 
defects when you purchased the drive. Some of the better 
drives contain this information in firmware on the controller 
card and you can skip this step. Drives of this type include 
the CDC Wren III and the Seagate “М” drives (e.g. the 
ST225N). Note that you must enter the defects in order of 
increasing cylinder number and you are not permited to 
have any defects on cylinder O. 

5). Next choose Format from the SCSI menu. You should see 
the drive activity light (that little red LED) light up on your 
drive and it will probably stay on for between 3 and 15 
minutes (the Wren III takes 18 minutes and my Seagate 
ST4051 takes 2). Your drive is now being formatted. You 
should also be able to hear the head postioning motor or 
voice coil moving the head as it formats the drive. If the light 
stays on for more than 20 minutes, or if you cannot hear the 
head moving, something is probably wrong. This is not 
always the case as I cannot hear the head moving on the 
Wren III when it is formatting. Be patient the first time. 

6). Now use a driver installer program to install a driver on 
your hard disk. You can use Apple's Generic SCSI Installer 
for this purpose, but be forwarned that this driver has bugs 
andthe data on your drive will eventually become corrupted 
and lost after about 20 hours of use. There are a few public 
domain programs that will also do this. Or you can wait for 
my next article! 

My next MacTutor article will include a driver that works on 
all three Macintoshes (Mac Plus, Mac SE and Mac II). I will 
include subroutines that can be added to this program to allow 
you to install this driver. 


Build you own Macintosh Hard Disk using 
the Control Data Wren lll 
Paul L. Derby,Control Data Corporation 
P.O. Box 0,Minneapolis, MN 55420-2028 
612-853-5986 
With the introduction of the Macintosh Plus, connection of 
computer peripheral devices that attach to the Small Computer 
Standard Interface bus (SCSI connection) is fairly straightfor- 
ward. Quite a few SCSI hard disk drives are available on the 
market with capacity and prices running from 20MB for around 
$600 to 172MB for around $6,000. There is also quite a variance 
in drive quality and reliability. If you are willing to put together 
a few pieces to make your own disk drive, you can have a top 
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quality Wren III 156MB drive made by MPI, Inc. for around 
$2,000. (This is the same drive Sony, a disk manufacturer, chose 
to place in their commercial workstation hardware.) 

Here are some of the technical specifications on the Wren III: 
16.5 ms average seek time with a 10 Mbits/second data transfer 
rate. А SCSI controller is integral to the drive as well as 
termination resistors. Typical average seek time is 18.5ms with 
controller overhead. If the head is already positioned single track 
seek time is 6 ms. Seek time with full stroke of the read/write 
head is 42ms. It takes about 15 minutes to format the drive. 
Sector interleave is 1 to 1, although the speedof the Mac SCSIbus 
cannot keep up with the data transfer rate of the Wren. The SCSI 
controller takes care of transferring the data to the Mac at the 
speed the Mac can handle. 

The Wren is very reliable with a service life rating of 30,000 
hours (5 years). 

If you want to put together you own Wren disk system, there 
are 4 pieces to acquire: (1) the actual disk unit with the integral 
controller, (2) a cabinet with power, fuse, fan, and mounting rails, 
(3) the connectors and cables to attach the drive to the Macintosh, 
and (4) software to format, install, and access the disk. 

The disk is available from a number of electronics distribu- 
tion companies such as Arrow Electronics, Kierulff Electronics, 
MTI, and Duccomun. The disk is an MPI Wren III (or a CDC 
Wren III), model number 94161-155 and sells for around $1850. 

An enclosure for the disk that includes a 75 watt switching 
power supply, fuse, fan, on/off switch, power cord and mounting 
rails, plus the cut outs to accommodate the two SCSI connectors 
is available from Microware Inc. for $185. 

Two cables are needed to connect the Wren to the Mac. One 
cable is needed to connect the controller on the Wren III to the 
connector on the rear of the enclosure. The other cable goes from 
the disk enclosure case to the Macintosh. Apple sells the second 
cable that goes from the DB25 connector on the rear of the Mac 
to the back panel of the disk enclosure. The first cable you build 
as follows: 

Buy two industrial Amphenol 50 pin F57 connectors (or 
equivalent) and one 50 pin IDC connector. Use a bench vise to 
press the connectors onto 50 conductor flat ribbon cable. Thread 
the ribbon cable through the cutouts on the back panel of the disk 
enclosure before pressing the connectors onto the cable. 

Assembly of the unit is very straightforward. Remove the 
power supply by unscrewing the two screws that secure it from 
the bottom of the enclosure. Slide the Wren into the hole in the 
frontof the disk enclosure and secure it with four 6-32 screws and 
washers. Connect the ground wire from the power supply to the 
ground spade on the Wren. Plug the power supply cable into the 
Wren power socket. Atthis time itis a good idea to power up the 
drive and make sure the voltage from the power supply is within 
specification for the Wren. The 5 volt output should be between 
4.75 and 5.25 volts with the drive running. If itis not within these 
voltage limits then you gently rotate the trim potentiometer 
located at the bottom center of the power supply. Set the 5 volt 
line as close to 5 volts as you can and then check the 12 volt side 
to make sure it is 12 volts +5%. When both the 5 and 12 volt 
supplies are within tolerance, power down the drive and secure 
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the power supply board. Install the cable between the Wren and 
the rear panel of the enclosure. Attach the Mac and you are ready 
to use software to prepare and use the drive. 

There are 3 pieces of software needed to use the Wren on the 
Mac Plus. A disk format program is needed to format the disk 
into 512 byte sectors (See Tim Standing's Format program in this 
issue). After formatting, an installer program is run to place the 
correct SCSI driver information on the disk. The last piece of 
software is a special file called an INIT file that is placed in the 
system folderon the floppy disk used to boot the Macintosh. This 
file loads the driver during boot time. On the Mac SE, the INIT 
file is not needed and the Wren drive can be booted directly. 
These pieces of software are available from an independent 
software development company, Carl Nelson & Associates, for 
a very reasonable licensing fee. Youcan also use Tim Standing's 
software that he is presenting in a series of articles in MacTutor. 

After the disk is initialized and the install process completed, 
using the drive is fairly straightforward. You use a floppy with 
the special INIT file in the system folder to boot up the Mac Plus. 
All the Wren drives that are on line will then come up. To run 
from the Wren double click on the FINDER icon in the system 
folder on the Wren to switch-launch to the Wren. The disk icon 
for the Wren will then be in the upper left position on the desktop 
and you can eject the floppy that was used for booting. The 
reason a floppy has to be used to bring the drive up is because 
Apple does not follow the SCSI protocol in the code located in the 
Mac Plus Roms. If you try to boot the Wren directly, the Apple 
SCSI routine in the ROM causes the Wren to hang in a loop. The 
Wren SCSI implementation strictly follows the ANSI specifica- 
tion. The MAC II and MAC SE ROMS fix this problem. 

Even with the hassle of booting the Mac from a floppy on the 
older Macintosh systems, the price, speed and capacity of the 
Wren are well worth the slower boot up process. This drive is 
especially suited as a file server an a Mac running Apple Share. 

Here are some more details on where to obtain parts: 

Wren III disk, Model 94161-155, SCSI interface, 512 byte 
sectors. Distributors are Arrow, MTI, Duccomun Data, and 
Kierulff. You can call Dave Johnson at Kierulff in Minneapolis 
at 612-941-7500 to find out which Kierulff office has the drives 
in stock and the closest outlet to you. Kierulff sells the drive for 
around $1850. 

The disk case and power supply are available from Microw- 
are Inc.,41711Joy Road, Canton, MI 48187, telephone 313-459- 
3557. You need a Beige tape case with a 75 watt power supply, 
part number 900014. This unit includes a fuse, fan, line cord and 
switch. It will run either 110V or 220V by moving a jumper on 
the power supply card. The power supply also runs fine on a 
220V to 110V transformer if you want to use it temporarily on 
European trips. The enclosure costs around $185. 

Amphenol 50 ріп F57 type receptor connectors. Part number 
850-57F-40500-20. These connectors cost about $8.27. They 
are solderless and not reusable so you may want to buy an extra 
justto practice on. In Minneapolis the only industrial Amphenol 
Distributor is Newark Electronics at 612-331-6350. 

50 conductor flat ribbon cable is available most anywhere in 
100 foot rolls. Gopher Electronics, 222 E. Little Canada Rd, St. 
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Paul, telephone 612-483-3322, will sell this stuff by the foot. All 
you needi s about 2 feet to make the cable with some left over for 
mistakes. 

The 50 pin IDC connector to the Wren is a Belden 880J050 
or an A P Products 925110-50-R. These cost around $7.00 each 
and you need one. Both Newark and Gopher Electronics sell 
these. 

The software is available from Carl Nelson & Associates, 
4007Nassau Place, Everett, WA, 98201-4855 telephone 206- 
252-6897. 

You will need four 6-32 x 3/8" pan head screws and washers 
to mount the disk in the enclosure. You will need four 4-40 x 3/ 
8" screws, nuts, washers, and lock washers to mount the two 
connectors in the disk enclosure back panel. 


a Tim Stending 
н 2/24/87 
н An automatic routine to build my output for me. 
n 
Unalias make 
(npw)tools:meke -f (tardir)mekef ile > (Scratch}makeout 
(Scratch)makeout 
exit 
*? File: MekeFile 
а 


* MakeFile for Formatting program for MacTutor An Low 
* Level formatting of a SCSI hard disk drive. Note if 
® resource file has been changed, run first Rez then 
8 Link. Rez sometimes trashes code resources. 


Format ff Format.r 
Rez -p Format.r -o Format 
Format ff Format.a.o BuffStuff.a.o 5С51.8.0 Format.r 
Link -p Format.a.o BuffStuff.a.o SCSI.a.o à 
-0 Format -1 > Format.Map 
Formet.a.0 ј  Format.a FormatEqu.a 
Asm -p -wb Format.a 
BuffStuff.a.o f  BuffStuff.a FormatEqu.e 
Asm -p -wb BuffStuff.a 
SCSI.a.0 f  SCSI.a FormatEqu.a 
Asm -p -wb SCSI.a 


зжжжжжажажах File FormatEqu.a **** 
Бы ыы ыы ыр. 


; А list of equates used in the SCSI formatting progrem. 


; Menu Bar resource numbers 


AppleM EQU 128 
FileM EQU 129 
EditM EQU 130 
SCSIM EQU 131 
; Dialog box resource numbers 
Abou tRN EQU 128 
Se lAddrRN EQU 129 
ParamRN EQU 130 


EDef ect sRNEQU 131 
AboutItem EQU 1 


DialWLen EQU 178 j lenght of window storage for 


,dialog box 
; Event Processing Equates 


AllEvents EQU 
EventMask EQU 


$0000FFFF 
$FFFF 


; Codes used in error dialog box for SCSI Manager traps. 
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Reset EQU $40 


Get EQU $41 
Select EQU $42 
Command EQU $A3 
Complete EQU $A4 
Read EQU $A5 
Write EQU $46 
Install EQU $A7 
Stat EQU $A10 


; Codes used in error dialog box for SCSI commands. 
RezeroUnitEQU 1 

TestUReadyEQU 0 

FormatUnitEQU 4 

ModeSe lectEQU $15 


MaxTicks EQU 108000 ‚мах 8 of ticks to wait for 
‚а SCSI command to complete 
MaxAddr EQU 6 ; largest SCSI address 


MaxCyl ind EQU 2048 
MaxHeads EQU 16 ;,lergest number of heads 
MaxBF I EQU $ 10000000 
; Offsets for input buffer used when inputting disk surface 
; defect information (relative to the beginning of that 
record). 


Cy1BBuff EQU 0 ;offset for cylinder field 
HeadBBuf f EQU 4 ;offset for head field 
BFIBBuff EQU 8 ;offset for bytes from index field 


; Offset for each record in output buffer (relative 
; to the beginning of that record). 


CylOut EQU 0 ;Offset for cylinder 
HeadOut EQU 3 ;Offset for head 
BFIOut EQU 4 ;Offset for byte from index 


; Equates for buffer sizes. Note there are two buffers for 
; defects, one for input, enother reformated one for output 
; during the Format Unit command. 
MaxBBs EQU 60 ,Meximum number of defects 
BedBRecLenEQU 16 і8іге of each defect record for 
; input buffer 
MaxBBListLen EQU 
,for input 
MaxBBOutLen ҒО) (MaxBBs*8 )+4 
,Unit command 
ModeSe 1BytesOut EQU 22 ;bytes transfered in 
; Mode Select command 
ParamBufflen EQU 38 j length of SCSI command 
;,peremeter buffer 
;length of command buffer 
; length of string buffers 
;lenght of class Ø commands 
;length of class 1 commands 
Pseudo program buffer length 
;Offset for cylinder low byte 


CBuf f Len EQU 10 
StrBuffLen EQU 256 
CommLenS EQU 6 
CommLenL EQU 10 
PProgLen EQU 30 
CylOut LB EQU 2 
CylOut. MB EQU 1 
CylOut. HB EQU 0 ;Offset for cylinder high byte 


Бы File:BuffStuff.a exeeeexeees 
ЖОККА 


д 
7 
д 


; manipulating the buffers. 


BLANKS ON 

IMPORT | (BadB_List, BadB_Num, BadB. Out ):DATA 
INCLUDE —— 'FormatEqu.a' 
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,lergest number of cylinders 


jbigest Bytes From Index value 


MexBBs*BedBRecLen ;length of defect buff 


j length of defect buffer 
; for output during Format 


;Offset for cylinder middle byte 


; This file contains a couple of subroutines that аге used for 


; 
7 
‚ 
‚ 
‚ 


ClearBuff PROC 


movem. 1 D2/A0, -CSP) 


This is used to clear a buffer. 
in Аб and the length in bytes in 00 Clong word value). 


PROC ClearBuff 


It gets the address 


EXPORT ;subroutine for export to other 
,moduals at link time. 


;save registers 


subq 81,00 ;D@=count-1; branch after clr.b 

blt.s exit ;exit if passed buffer length =@ 
buf -100p 

clr.b (А0,00.1) ¿clear the byte 

dbra 06,60? loop jbranch when 00›0 
exit 

movem. 1 CSP?*,D0/A0 ;restore the registers 

rts 

ENDPROC 


PROC OutBuf f 
used as the 
block minus 


in order of 
record are: 


Registers: 


D1 Scratch 


“е We We & we We We We We We We We We We We We We We 


Ou tBuf f 
; Equates for 
ByteCount EQU 


movem. | 


in the bad block records. 


OutBuff takes list of bad blocks and reformats so it can be 


defect data block that gets transfered after the 


format command. First we place the size of the defect data 


the 4 byte header in byte 3. Then we load 

They must have aready been sorted 
increasing cylinder number. The fields in each 
3 bytes for the cylinder, one byte for 


the head number and a long word for the bytes 
from index value. 


Ай Points to curent position in BadB.L ist 


Cour sorted list of bed blocks used for input) 


; A1 Points to current position in BadB_Out 


Cour output buffer used in formatting) 


00 Loop index 


PROC EXPORT 


offset at beginning of bad block output buffer: 
3 


00-01/А0-А1,-(АТ) ;save registers on stack 


; Clear the output buffer before we start transfering records. 
1 


loop 


into record, 


move. | 


BadB_Out(A5), A 
*MaxBBOutLen, DØ 
ClearBuf f 


BedB.NumCA52,D0;get the number of defects 
exit ,exit if it's zero 


81,00 ,adjust 00 Сфга after transfer) 
BedB.List(A52,A0 initialize Аб 

BadB. Out (A52,A1; initialize A1 

D1 ;clear scratch 

BadB. NumCA5),D1 

83/01 ;multipy count by 8 bytes 
D1,ByteCount(Al) ;р1асе LSB of count in header 
84 A1 ;incr output pointer to 1st rec. 


Cy1BBuff САЙ ),0 1; load cylinder! in scratch 


D1,CylOut.LBCA1)  ;move low byte into record 
#8,D1 

D1,Cyl0ut_MBCA1)  ;move middle byte into record 
88/01 

D1, CylOut_HBCA 1) 

gh byte into rec rd move.b 3*HeadBBuf f CAO), 
1) jmove head numbe 


;moving byte value of long 
BFIBBuffCA2),BF IOutCA1) 
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j transfer Byte.From Index value 
JAO points to next input record 
АІ points to next output record 
,decrement loop counter & repeat 


adda.1 %16,А0 
edde.| &8,А1 
дога — DO,Loop 


exit 
тоует.1 CA7)*,D0-D1/AQ-A1 ;restore registers 
rts 
ENDPROC 
END 


.XXXXXXXXX File: SCSI. XiXxkxxkkxx 
ЖЖЖЖ КККК 


~ 


This file contains al] the items in the SCSI menu. It also 
contains the SCSI primatives for comunication with SCSI hard 
disks. 


Note: All the symbols that are declared or imported before 
start of the first module (PROC, MAIN or RECORD) are def ined 
for all modules in this file. Forward references to other 
modules in a file must be imported. 


we "e We We We Ws We We We %» 


INCLUDE ‘FormatEqu.a’ 
LOAD ‘Traps.d’ 
LOAD ‘ToolEqu.d’ 
LOAD ‘SysEqu.d’ 
LOAD 'QuickEqu. d’ 
LOAD ‘SCSIEqu.d’ 


EXPORT (Res,Last_Cmd,CompStat,CompMsg):DATA 
EXPORT (BadB.Num):DATA 


Addr ds.w 1  ;address of hard disk 

Heads ds.1 1 ;number of heads on hard disk 
Cyls ds.1 1 number of cylinders on hard disk 
WrtPreCompds .1 1 cylinder to start write precomp 


Interleaveds.w 1 ;interleave number to be used 
StepCode ds.w 1  ;type of step pulse used 


RedWrtCur ds.| 1 ;cylinder to start reduced write cur 
9 


CompStat ds.w 1 
CompMsg ds.w 1 


,Stetus from _SCSIComplete 
message from _SCSIComplete 


Res ds.w 1 
Last. Ста ds.w 1 


jresult from SCSI commands 
j last command executed 


BadB_Num ds.1 1 total number of bad blocks 
IMPORT (DialogPort, ItemType, I temHandle, ItemRect):DATA 
IMPORT CEventLoop,DefButton, RadioHiLite):CODE 
IMPORT CCountOff ,ExtractNumb, Sor tBuf f , OutBuf f >): CODE 
IMPORT CErrorProc,ClearBuf f 2: CODE 
IMPORT (DialogBuff ,ButtonHit?:DATA 
IMPORT (StrBuff 1, StrBuf f2, StrBuf f 3, StrBuf f 4):DATA 


Buffers RECORD EXPORT 
EXPORT CCommandBuf f , PseudoProg, ParamBuff > :ОАТА 
EXPORT (BadB.L ist, BadB. Out ):DATA 
ALIGN 2 


CommandBuff ds.b  CBuffLen 
PseudoProgds.b РРгодіеп 
ParamBuf f ds.b 
BadB_List ds.1 


jbuffer for SCSI commands 
;buffer for pseudo program 
PeremBuffLen ;buffer for parameters 
MexBBListLen ^ ;buffer area for entering 
; end sorting bad blocks 


BadB.Out д5.1 MaxBBOutLen jbuffer area for output to 
jto the disk drive 
ENDR 
PROC бе АдагРгос 


Gets the address of the device to be formatted 
from the user. Then tests to see if device is connected 
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; end if device is ready to be formatted. If either of these 
; ere false, it jumps to ErrorProc Cerror handling procedure). 


SelAddrProc PROC EXPORT 
IMPORT (Hd_Select,HD_TestUnit,HD_Discon): CODE 
IMPORT CUnHiLite,ResetDisk ):CODE 


с1г.1 -(АТ) 

move.w *SelAddrRN, -CA7) 
pea DialogBuf fCA5) 
move.] 3-1,-CATD 

Ge tNewD ialog 


;Ѕрасе for pointer to dialog 
jselect addr dialog resource? 
j;push pointer to dialog stor 
теке dialog top most window 


тоуе. 1 (CA7),DialogPortCA5) ;ѕауе pointer to dialog 

; leave а copy on the stack 
;for call to _SetPort 

Se tPort 

lea DialogBuffCA5),A4 ;pass address of dialog record 
jsr DefButton jmake default = “Select” 
move.w 810,00 ;make Mac’s address grey 

jsr UnHiLite 


; Register ussage: 
00 Radio button that was selected, now must be unselected 
01 Radio button that was just clicked on to be selected 


; Initialize 00 and D3 for first call to RadioHiLite. 00-0 
; is flag for no radio button to deselect. 01=3 is to set the 
; default SCSI address = 0. 

cir.) 00 

moveq.1 83,07 


NotYet 
move.w 07,01 
jsr RadioHiLite 


jupdate D1 Cpass to RadioHiLite) 
;chenge radio button selected 


с1г.1 -CAT) juse standard filter proc func 
pea ButtonHitCA5) 
-ModalDialog 


cmpi.w %2,ButtonHitCA5) 
ble EndDialog 

move.) 07,00 

move.w ButtonHitCA5),D7 
bra.s NotYet 


маз select or cancel hit 
jyes, so close up dialog 

00 = id of old radio button 
;07 = id of new radio button 

; loop back for next mouse down 


EndDialog 
move.| DialogPort(A5),-CA7) ;pass addr of Dialog Rec 
-CloseDialog ;close dialog 
cmpi.w %2,ButtonHit(A5) ;маѕ ok button hit 
bit Continue ;yes 


jmp EventLoop jno, go get next event 
Continue 

Subq.w #3,07 ;07 = last radio button hit so 
jsubtract item # for radio 
jbutton "0^ 


move.w D7,Addr(A5) ;07 now equals address selected 


jsr ResetDisk 
tst.w  Res(A5) 
bne ToErrorProc 


jreset SCSI bus 
,did we succeed 
jno, go handle error 


This next block of code, through end of this procedure is 
an example of how 811 SCSI commands ere done. You can 
replace the SCSI command Test Unit Ready with any other 
SCSI command. 

The Mode Select апа Format Unit commands used in FormatProc 
differ only in that data is transfered after the command. 


we We We We Be We 


First get control of the bus and select target device. 
jsr HD_Se lect ;до get control of bus and 

jselect device 

jdid we succeed 

jno, go handle error 


we 


tst.w Веѕ(СА5) 
bne ToErrorProc 
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Second, we clear the buffer we use to construct the SCSI 
command in. 
lea CommandBuf f (A5), Ad 
move.] ®CBuffLen, Dd 
jsr ClearBuf f 


we We 


;раѕѕ address of buffer іп Аб 
;pess buffer size in DØ 
;clear buffer 


; Third, we construct the command. This one has no parameters 
in the CDB (Command Desciption Block), so only have to move 
the SCSI OP code into the CDB. 


we We & 


move.b *TestUReady, CommandBuf f(A5) 
; move OP code into byte 

; lof the CDB 
cir.w -СА7) ; clear space for trap result 
pea CommandBuff CA5); pass address of CDB 
move.w "CommLenS,-CA7); pass length of command. 

; This is а class 0 SCSI 

; command, length is 6 bytes. 


Fourth, we send the command and test if it succeded. 
_5С51Ста send command to target 


we 


move.w *TestUReady,Last_CmdCA5) 
move.w САТ )+, ВеѕСА5 ) 
bne ToErrorProc 


;store command id 
;test result, an error? 
уез go to error proc 


Then, we wait for the target device send the Status and 

Message bytes. The target device will then release the Mac. 
поуе.1 810,00 ;pess number of ticks to wait 
jsr HD_D iscon jproc that handles .SCSICom- 

plete 

tst.w  Res(A5) 

bne ToErrorProc 


we Ge 


;SCSI Protocal Error? 
jyes, go handle display error 


; Lastly, we test the Status byte returned by -SCSIComplete. 
; This is the SCSI command result code. It will tell us about 
; the drives condition and if it is ready to be formated. 


move.w *TestUReady,Last_Cmd(A5) ;store command id for 
,error handling proc 

cmp.w %3,CompStatC(A5); is there a Write Fault? 

beq ToErrorProc ;,yes, go to error handler 


cmp.w  *4,CompStat(Ab2; is the Drive Not Ready? 
beq ToErrorProc jyes, go to error handler 
cmp.w 820 Сопрб%а( (Аб)  ,;SCSI command supported? 


beq ToErrorProc 
jmp EventLoop 


70, go to error handling proc 
ToErrorProc 

jmp ErrorProc 

EndProc 


: PROC ParamProc 


: for formatting drive. We then extract the values from the 
: TextEdit fields and place the hex values in the appropiate 
; global variables. All values are checked against maximum 
; values to make sure they are reasonable. 


2 
User is given dialog box to input paremeters used 
д 
д 
7 


ParemProc PROC EXPORT 

clr.1 -(A7) ,Spece for pointer to dialog 
move.w *ParamRN,-CA7) ;paremeter dialog resource numb. 
реа DialogBuff CA5) ;push pointer to dialog storage 
тоуе.1 #-1,-CA7) ;dialog on top of all windows 
-GetNewDialog 

move.1 CA72,DialogPortCA5) 
-SetPort 

lea DialogBuffCA5),A4 ;pass address of dialog record 
jsr DefButton ;make “OK” button the default 


jsave pointer to dialog 
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Now we set up our dialog box. First two calls to RedioHiLite 
have 00-0 as a flag for no radio button to unselect 
Register ussage: 

00 button that wes selected, now must be unselected 

01 button that was just clicked on, to be selected 

06 Interleeve Button that is currently selected 

D7 Step Rate Button that is currently selected 

moveq.1 83,06 jdefault interleave = 1:1 

moveq.1 87,07 ;default step pulse = 3 msec 


"e Be e We We We Be 


; High light default interleave and step pulse radio buttons. 
move.w D6,D1 


clr.w 00 
jsr RadioHiLite 
clr.w 00 


move.w 07,01 
jsr RadioHiLite 


NotYet 
clr.1 -CAT) j;use standard filter proc func 
pea ButtonHitCA5) ;push addr of storage for item! 
-ModalDialog 
move.w ButtonHitC(A5),D1  ;move item number to 01 
cmpi.w 82/01 ;was ОК or Cancel selected? 
ble EndDialog ;yes, go close up dialog 
cmpi.w 89/01 jwas text edit item hit 
bgt NotYet ;yes, loop back for next event 


cmpi.w 86/1 
bgt StepRate 


,мав interleave radio button hit 
;no, must be step rate button 


; Interleave radio button was selected. Update D6 and select 
; the correct radio button. 

move.w 06,00 

move.w 01,06 

jsr RadioHiL ite 

bra.s NotYet 


; Step rate radio button was selected. Update D7 and select 
; the correct radio button. 
StepRate 

move.w 07,00 

move.w 01,07 

jsr RadioHiLite 


bra NotYet 
EndDialog 
cmpi.w #2,ButtonHit(A5) ;was “Cancel” selected? 
bit Continue jno 
bra exit yes, so exit 


; “OK” button selected so we can update the global variables 
; that contain the step code and the interleave values. 
Continue 

Subq.w #2,06 

move.w D6, Inter leaveCA5) 

subq.w #87,D7 

move.w D7,StepCode(A5) 


; For each of the TextEdit fields we place the address of the 

; global variable in АЗ, the item * in 00 and maximum value 

; in D3. We then call ExtractNumb to get the hex, insure that 

; it is not over the maximum value, and place hex number in 

; the global variable. 
lea Heads(CA5), АЗ 
тоуе.1 *10,D0 
move.] *MaxHeeds,D3 
jsr ExtractNumb 


,extrect number of heads from 
;item number 10 


lea СуТЅСА5), A3 
move.] 811,00 

move.] *MaxCylind,D3 
jsr ExtractNumb 


extract number of cylinders 
;from item number 11 


lea RedWr tCur CA5), АЗ 
тоуе.1 %812/00 


extract reduced write current 
;cylinder from item #12 
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move.1 CylsCA52,D3 
jsr ExtractNumb 


lea WrtPreComp(A52,A3 ;extract write precompensation 
поуе.1 %13,00 ,eylinder from item 813 
move.1 CylsCA5),D3 

jsr ExtractNumb 


Exit 


поуе.1 DialogPort(A5),-CA7) ;раѕѕ ptr to Dialog rec 


-CloseDialog ;close dialog box 
jmp EventLoop ,return to event loop 
EndProc 


PROC EDefectProc 


Here we ask the user to enter the defects that are listed on 
the sheet that came with their disk drive. Can enter as 

many es 60 defects. Since dialog box only has room for 12 
defects, we ask the user to hit “More” button if they have 
additional defects. We give the user a dialog box when they 
cannot enter any more defects. 


Register Ussage: 
00 Index for next item in dialog is EditText that 
we ere going to remove a value from 
D6 Index for record being input in defect list 
index is byte index of first field in record, 
F not actual record number 
EDefectProc PROC EXPORT 


* о We We We We We We We We We We We We We 


сіг.1 BadB_NumCA5) ;clear global for 8 of defects 
; Clear our defect buffer. 
jpass buffer size іп 00 

jpass address іп Аб 


;90 clear buffer 


move.] *tMaxBBListLen,DO 
lea BadB.L ist (A5),A0 
jsr ClearBuf f 


LoopForMore 
clr.1 D6 ¿clear buffer record index 
clr.1 -CAT) ;space for pointer to dialog rec 


move.w "EDefectsRN,-CA7) ;Enter Defects Dialog res! 
pea DialogBuff (A5) ¿pass ptr to dialog storage 
поуе.1 8#-],-(АТ) ;meke this window on top 


Ge tNewDialog ,get dialog 
поуе.1 CA7),DialogPort(A5) X ;save pointer to dialog 
-SetPort 


lea DialogBuffCA5),A4 ;раѕѕ address of dialog record 
jsr Def Button joutline default button 


NotYet 
clr.1 -(АТ) ,use Standard filter proc function 
pea ButtonHit(Ab) ;place for button hit 
-ModalDialog ;hendle dialog events 
cmpi.w *3,ButtonHit(Ab)  ;is “Cancel” button hit? 
bit EndDialog ;по, “Моге” or “OK” buttons were hit 
bgt NotYet jno, not a button, get another event 


; User hit “Cancel” button, so clear defect count and return 
; go close dialog box 

с1г.1 BadB_NumCA5) 

bra exit 


; We want to close up the dialog, but first we must extract 
; the defect data that the user has entered. 
EndDialog 
поуе.1 BadB_NumCA5),D6;move number of defects to 06 
181.1 44,06 ;multiply by 16 to get byte 
j index for first field in 
jnext empty record 
lea BadB_ListCA5),AS ;Аб points 1st byte of buffer 
AddToBuf f 


move.1 %3,00 ,first item is 4, so put 3 in 00 
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LoopAddBuf f 

; First we extract the cylinder number. 

We use the ExtractNumb procedure 

which takes the address for the result in A3, the 
maximum value in D3 and the item number in 00. 


we We We 


eddq.! &1,00 ;increment 00 by 1, next item 
lea Cy1BBuff CA2,D6.L 2, A3 

move.] "MaxCylind,D3 

jsr ExtractNumb 


we 


Next we extract the head number 
eddq.! 81,00 
lea HeadBBuf f CA9,D6.L),A3 
тоуе.1 *MaxHeads,D3 
jsr ExtractNumb 


Lastly we extract the Bytes From Index value. 
addq.1 81,00 
lea BF IBBuf f CAS, 06.L),A3 
поуе. 1 "MaxBFI,D3 
jsr ExtractNumb 


we 


Test to see if the cylinder number was 0. If so ignore this 
record as it was either empty or invalid. Most controller 
cards cannot take defects in track 0. 

tst.|1 CylBBuffCAd,0D6.L) ;is cylinder value valid 

bne IncrCounters Ме5 increment counters 


we We Ve 


Otherwise, don’t increment counters and next record will 
overwrite this one which was invalid. 
cmpi.1 5339,00 ;have we reached the last item 
beq Exit ;yes, go close dialog box 
bra LoopAddBuf f ‚по, go extract next record 


we We 


; Cylinder number is not equal to 8 so this is a valid defect. 


IncrCounters 
add.1 %BadBRecLen,D6 ; increment buffer index 
стр1.1 %(MaxBBs*BadBRecLen),D6 ;іѕ our buffer full 
beq.s Exit Ме5, so exit 


стрі.1 839 00 
bne LoopAddBuf f 


Exit 
Isr.1 84/06 ;byte count/16 = number of defects 
тоуе.1 D6,BadB_Num(A5);store defect number in global 
тоуе.1 DialogPort(A5),-CA7) ;раѕѕ pointer to dialog 
-CloseDialog ,close up dialog 
стрі.1 %68,BadB_Num(A5) ;аге there too many bad blocks 
beq.s NoMoreAlert ;уеѕ, go put up alert 
cmpi.w %2,ButtonHitC(A5);did user hit “More” button (82) 
bne ToEventLoop П0, 50 go to event loop 
bra LoopF orMore уев so put up dialog again 
ToEventLoop 
jmp EventLoop 
NoMoreA lert 
move.w 9134,-CAT) ,get out of space alert 
clr.1 -<САТ) juse standard filter proc function 
с1г.м -САТ) 
CautionAlert juse а caution alert 
clr.w (АТ) 


jmp EventLoop 
EndProc 
PROC FormatProc 


Formating procedure. This is where we sent the drive 
parameters in а Mode Select command. We then send the drive 


we We Ve De 
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££ 


* 
д 
2 


FormatProcPROC 


7 


. 
д 

. 
д 


д 


defects with the Format Unit command. Апа then the drive is 


; ready to use with а driver installing program. 


EXPORT 
IMPORT CHD-Select,HD.Discon,WriteDisk2:CODE 


First we put up а dialog box to make sure the user wants to 
format the drive. 


Make String buffer 81, 1 character long. Then move the hex 
value in the low order byte of Addr (the SCSI address of the 


; target device) into the string buffer and convert to ascii. 


move .b 
move .b 
add.b 


81, StrBuf f 1CA5) 
1*Addr CAS), 1*StrBuf f 1СА5) 
8930, 1*StrBuf f 1(A5) 


clr.b 
clr.b 
clr.b 
pea 
pea 
pea 
pea 
-PeremText 


StrBuf f 2(A5) 
StrBuf f 3(A5) 
StrBuf f 4(A5) 
StrBuf f 1СА5) 
StrBuf f 2(A5) 
StrBuf f 3(A5) 
StrBuf f 4(A5) 
,Substitute String buffer 1 for 470” 


;clear all other string buffers 


move.w 5132,-CAT) ;get format alert dialog box 


clr.1 -(АТ) juse standard filter proc function 
clr.w -САТ) 

_CautionAlert 

cmpi.w ®1,CA7)+ X ;did user hit cancel? 

bne Exit jyes, so exit 


User wants to Zap Drive, so let ‘em have it! 
Construct a data block to place parameters that we will send 


: with the Mode Select command. 


ZapDr ive 


д 


we Ge We 


me 


we ә 


wee We 


First we clear the data buffer 


lea ParamBuff(A5),A8 ;раѕѕ address of buffer 

move.] "ParamBufflLen,D@ ;раѕѕ length of buffer 

jsr ClearBuff ;clear buffer 

clr.1 00 ,cleer DØ, used for scratch 
;header 

move.b %8,$3САб) ;3rd byte = size of descriptor 
;list 
,descriptor list 

move.b 32,$ACA0) ;high byte of sector size ($200) 
;Drive Parameter List 

move.b 3*1,$CCA0) ;List Format Code: (1 = soft 


,sectored drives, 2= hard 
j;sectored drives or 
removable media drives) 


Place word value of cylinder count into buffer. We must do 
this as two bytes because the wored in the output buffer is 
at an odd address 


move.w 2+CylsCA5),D8 
move.b 00,%ЕСА0) 


lsr.] 88,00 
move.b 00,%0СА0) 


jmake sure $ECAO) has LSB 
;now move in high byte of word 


Move byte value of head count into buffer. 
move.b 3+Heads(A5), $FCAS) 


Move word value of Reduced Write Current Cylinder into 
buffer. 
move.w 2*RedWrtCurCA52,$10CA0) 


Move word value of Write Precompensation Cylinder into 


buffer. 
move.w 2*WrtPreComp(A52,$12CA0) 
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) 


д 
) 


a 


д 


Move byte value of Step Pulse Code into Buffer. 
move.b 1*stepcode(A52,$15CA0) 


Now we send the Mode Select Command and the parameter 
buffer. 


jsr НО. белесі ;get SCSI bus end select drive 
tst.w  Res(A5) ;did we succeed? 
bne ToErrorProc ;no, So go to error handling proc 


: Clear command buffer and construct command. 


lea CommandBuf fCA5),A9 ;pass address of buffer 
тоуе.1 ®CBufflen,D® ;раѕѕ length of buffer 


jsr Clear Buf f ;clear command buffer 
move.b 'ModeSelect,CA2)  ;move SCSI OP Code to byte 80 
move.b *iModeSelBytesOut,4CA2) ;move * of bytes to 
; transfer into byte 84 

cIr.w -САТ) jspace for trap error code 
move.] А04,-САТ) jpass address of command buffer 
move.w *CommLenS,-CA7);pass length of CDB 

;(Command Data Block), 

;class 8 command, so it 

;is 6 bytes long 
-SCSICnd ;send command 


move.w "ModeSelect,Last_Cmd(A5) ;store command id 


move.w (CA7)+,ResCA5) 
bne ToErrorProc 


;did command work? 
по, go to error handling proc 


Now we clear the pseudo progrem buffer 
WriteDisk to send the data to the controller card. 


lea PseudoProg(A52,A8 ;pass address of buffer 

тоуе.1 &РРгодіеп,00 ,pess size of buffer 

jsr ClearBuf f ;clear buffer 

lea PeremBuff(A5),A1  ;pass address of data buffer 

поуе.1 "ModeSelBytesOut,D@ ;раѕѕ * of bytes to 

jsr Wr iteDisk ; transfer & send data 

поуе.1 810,00 ;ра55 number of ticks to wait 

jsr HD_Discon 

tst.w  ResCA5) SCSI Protocal Error? 

bne ToErrorProc 

move.w *"ModeSelect,Last_Cmd(A5) 

cmp.w %$4,CompStat(A5)  ;is the Drive Not Ready? 

beq ToErrorProc ;yes, go to error handler 

cmp.w %$24,CompStat(A5) ;Was a bad parameter passed to 
j the controller? 

beq ToErrorProc ;уеѕ, go to error handler 

jsr HD Select 390 get control of bus and 
,select device 

tst.w  Res(A5) jdid we succeed? 

bne ToErrorProc ‚по, go to error proc 


Next, clear the buffer where we will assemble the СОВ 
lea CommandBuf f (A5), Аб ;pass address of buffer 


тоуе.1 f"'CBuffLen,DO jpass size of buffer 

js" ClearBuf f ;clear buffer 

move.b "FormatUnit,(A®) ;move op code into first byte 

move.b itInterleaveC(A5),4CAB) ;move byte value of inter 
; leave into byte 4 

tst.1 BadB num(A5) ,see if there ere disk defects 

beq NoDefects jno, Skip ahead 

add.b #$1C, 1СА0) ;plece flags to tell controller 


;thet defects are coming 
Call OutBuff to format defects so they сап be read by 


; controller card. 


jsr OutBuf f 
NoDefects 
сігін  -CAT) ;space for trap error code 
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move.] Аб, -САТ) ;pess address of СОВ 

move.w ®CommLenS,-CA7);class Ø command so pass 
; length of 6 bytes 

-SCSICnd ;send command 


move.w "FormetUnit,Lest Cmd(A5) ;store command id 


move.w (CA7)+,ResCA5) jdid _SCSICmd produce an error 
bne ToErrorProc jyes, go to error handler 


; If we are sending any info on disk defects, prepare buffer 
; for pseudo program and pass count bytes and address to 
; sending procedure. 
tst.1 BedB.num(A5) ;аге we sending any defect data? 
beq NoPseudoProg ;по, skip the next section 


; Clear pseudo program buffer. 
lea PseudoProg(A52,A8 ;pass address of buffer 
тоуе.1 fi'PProgLen,D9 ,pess length of buffer 
jsr ClearBuff jclear buffer 


; Pass address of data, and number of bytes to be transfered. 
; M still contains the address of the pseudo program buffer. 
Tea BadB_OutCA5),A1 
move.] BadB NumCA52,D0;move number of defects to DØ 


151.1 93,00 ;hultiply by 8 (8 bytes/defect) 

addq.1 84,00 зада 4 bytes for header 

jsr WriteDisk jsend info on defects 
NoPseudoProg 

move.] "MaxTicks, D@ ,pess number of ticks to wait 

jsr HD_Discon 

tst.w  Res(A5) ,SCSI Protocal Error? 

bne ToErrorProc jyes, go to error handler 


; Test Status byte from SCSI command to see if we passed a bad 
; parameter or if there is a defect on track 9. 
move.w *FormatUnit,Last_Cmd(A5) ;update command id for 
error handling proc 
cmp.w %$24,CompStat(A5) ;Was а bad parameter passed to 
jthe controller? 
beq ToErrorProc Ме5, go to error proc 
jmp EventLoop 


Exit 
jmp EventLoop 


ToErrorProc 
jmp ErrorProc 


EndProc 
: PROC ResetProc 


ГА 
М 
; This procedure is called from the menu handling routine. It 
; acts as glue between the menu handling code and the reset 
; Subroutine end allows us to re-use the reset subroutine. 
; (like in SelAddrProc). 
ResetProc PROC EXPORT 
IMPORT CResetDisk):CODE 


jsr Rese tDisk ;9go reset SCSI bus 


tst.w ResCA5) ;test result 

bne ToErrorProc jif error go to error handler 

jmp EventLoop ,else return to event loop 
ToErrorProc 

jmp ErrorProc 

EndProc 


PROC WriteDisk 


Procedure wor transfering data to the controller. This 
routine uses а pseudo program which contains a simple loop 
of three instructions. This transfer could have been done 


“е We We We We 
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7 


7 
LJ 
7 


) 


д 
. 
2 
i} 
д 


Ш 


e 
7 
. 
д 
д 
д 
LI 
д 
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using only the first end the lest instruction if we had put 
the transfer count that is passed іп 00 into the second 
peremeter of the first command. It would look exactly the 
same if it were being used for a read, except the .SCSIWrite 
trap would be replaced with _SCSIRead. Refer to IM volume IV 
for info on the Pseudo instructions. Note each instruction 


be the last instruction. Address of pseudo buffer is 
passed іп Ай. Address of p_buff is passed in А1. 
Transfer count is passed in 00. 
riteDisk PROC ENTRY 
movem.] D9-D2/A0-A1,-CSP) ;save registers 


) 
; 
; 
; 
; is а word followed by two longword parameters. SCSTOP must 
; 
; 
; 
W 


First command moves bytes to given address 
move.w "SCINC, CAS) 
move.] А1,2(А0) jaddress to be moved to or from 
тоуе.1 %1,6(А0) ,trensfer count in bytes 


Second command is loop 
move.w "SCLOOP, 10СА0) 
move.] 8-10 12(А0) гет addr 
move.] (00, 16(А0) ;loop count 


Third command = stop, no parameters 
move.w "SCSTOP,20CA0) 


сігін  -CSP) ;space for trap result code (OSErr) 
тоуе.1 A®,-(SP)  ;address of pseudo program 
-SCSIWrite 

move.w (SP)+,ResCA5) ;Store result 


move.w "Write,Last_Cmd(A5) X ;store code for type 
sof SCSI command 
movem.1 (SP )+, 00-02 /Ад-А 1 restore registers 
rts 
ENDPROC 
PROC HD. Select 
HD_Select tries to get control of the SCSI bus. If it does, 


; it then selects the device whose address is in Addr(A5). 


НО. Select PROC . ENTRY 


IMPORT CountOff : CODE 
movem.1 00-02/А0-А1,-(АТ) ;save regs on stack 


cir.w  -CAT) ;Space for result code 
-SCSIGet ,reserve the bus for our use 
move.w (CA7)+,ResCA5) ,Store result code 
beq.s ок ;go to ok2 if we succeeded 
move.w "Get,Last_CmdCA5) ;е1ѕе, store the last command 
bra.s exit запа return 
ok 
cir.w -САТ) ;space for result code 
move.w Addr(A5),-CA7) ; load SCSI address of hard 
disk 
-SCSISelect ;select device 
move.w САТ )+,ВеѕСА5) ,store result code 
move.w "Select,Last_Cmd(A5)  ;store last command 
exit 
тоуем. 1 (A7)*,D0-D2/A0-A1 ;restore registers 
rts 
ENDPROC 


PROC HD. Discon 


; Here we complete а SCSI command. We tell Mac how long to 


wait for target device on the SCSI bus to signal that the 
command has completed. This procedure receives number of 
ticks to wait in DØ. 


HDDiscon PROC ENTRY 
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тоуеп. 1 00-02/А0-А1,-САТ) ;seve regs on stack 


clr.w  CompStat(A5) 
clr.w X CompMsg(A5) 


clr.w  -CAT) 

pea Сотр5%8ХА5) 
реа СотрМ5асА5) 
тоуе.1 00,-(АТ) 


;Ѕрасе for result code 
;-SCSIConplete Status 
;-SCSIConplete Message 
;number of ticks to wait for 
completion of the lest 
,SCSI command 

-SCSIComplete 


move.w САТ )+, ВеѕСА5) ;store result code 
move.w "Complete,Last_Cmd(A5) ;store last command 
movem.1 (А72%,00-02/А0-А1 restore registers 

rts 

ENDPROC 


PROC InitGlobals 


Initialize the globals used to store information about the 
hard disk. Set all values to zero 


peng ee Wee We ә 


nitGlobals PROC EXPORT 
clr.w HeadsCA5) 
clr.w CylsCA5) 
clr.w WrtPreCompCA5) 
clr.w RedWrtCur(A5) 
clr.w Inter leaveCA5) 
clr.w  StepCode(A5) 
clr.1 AddrcA5) 


сіг.1  BedB.NumCA5) 


rts 
ENDPROC 
PROC ResetDisk 
This procedure resets the SCSI bus. It has a 
one second delay after the 
reset because the CDC Wren III drives take more than 
3/4 of а second to completely reset. Other drives may need 


longer delays after the reset. 
esetDisk PROC EXPORT 


2799-9 ete te 


movem. 1 00-02/А0-А1,-(АТ) ;save the registers 


clr.w« -САТ) ,spece for result code 
-SCSIReset reset the bus 

move.w (CA7)+,ResCA5) store results 

beq.s oki ;go to ok1 if we succeeded 
move.w ?Reset,Last Cmd(A5) ;е1ѕе cmd code for err Msg 
rts 


ok1 
move.l 5160,00 00 = number of ticks to wait 
jsr CountOf f ,jst to delay routine 
movem. 1 (А72%,00-02/А0-А1 ;restore the registers 


rts 
ENDPROC 
END 


;*®®®®®ї* File: Format.a f*ttrrrrnnnden 


; XXXXXXXxXxxxxxxxsxxxxxxxxtrxxxxxxxxxxxxx 


; 

; A formatting program for low level formatting of a SCSI 

; hard disk. Allows user to enter disk drive parameters and 
; information about defects. This file contains all 

; the standard code for Menus etc. It also contains the 

; procedures for error handling. 


BLANKS ON 


34 


INCLUDE 'FormatEqu a^ 
LOAD ‘Traps .d' 
LOAD ‘ToolEqu.d’ 
LOAD ‘SysEqu.d’ 
LOAD ‘QuickEqu.d’ 
LOAD ‘SCSIEqu.d’ 
LOAD ‘PackMacs .d’ 


; Note Export directives must be placed before a symbol is 
; declared. 


EXPORT (DialogBuff ,QuickDraw,ButtonHit,DialogPort):DATA 
EXPORT CItemType, I temHandle, ItemRect , MyPor t2: DATA 
EXPORT (StrBuff 1,StrBuff2,StrBuff 3,StrBuf f 4):DATA 


AppleMH 45.1 1 ;hendle for Apple menu 
FileMHH 895.1 1 handle for File menu 
EditMH 65.1 1 handle for Edit menu 
SCSIMH (4.! 1  ;hendle for SCSI menu 
DAName ds.b 255 ;space for DA’s name 
Window ds.1 

DialogBuffds.| DialWLen 

MyPort ds.1 1 


ButtonHit ds.w 1 
DielogPortds.1 1 
ItemType ds.1 1 
ItemHandleds. 1 1 
ItemRect ds.1 2 


StrBuff 1 ds.b X StrBuffLen 
StrBuff2 ds.b — StrBuffLen 
StrBuff3 ds.b StrBuffLen 
StrBuf 4 ds.b — StrBuffLen 


EventRec RECORD 20, INCR 


at dw 1 ; 

Message ds. 1 І: ; 

When ds. 1 |. ; 

Point ds.1 1. 3 

Modify dsw 1; 
ENDR 


; Note: The space for quickdraw globals must be declared. 
; Unlike MDS, the MPW assembler does not do it for you. 


QuickDraw RECORD , DECREMENT 
thePort ds.1 1 
ORG -grefSize 


; This is our program. 
Begin MAIN 
ALIGN 2 
IMPORT CInitManagers,LoadMenu, InitGlobals, EventLoop): CODE 
ме must import these symbols as they are not 
дес defined in this file. 


jsr Ini tManagers 
jsr LoadMenu 

jsr InitGlobals 
jmp EventLoop 


ENDMA IN 


; PROC Ini tManagers 
Initialize all managers that we might need. 


InitManagers PROC ENTRY 
IMPORT QuickDraw:DATA 


pea QuickDraw.thePortCA5) 
-Initoref 
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-InitFonts 

move.] "AllEvents,DO 
-FlushEvents 
-InitWindows 
-InitMenus 

clr.) -CAT) 
-InitDialogs 

-TEInit 

-InitCursor 

rts 


ENDPROC 


; PROCLoadMenus 


Subroutine called at start up time to load menus onto the 


4 


; heap, install them and then draw the menu bar. 


LoadMenu PROC ENTRY 


7 
М 
д 
2 


clr.1 -—(А7) 
move.w "AppleM,-CAT) ;"About...^ ID for Apple menu 
_GetRMenu ‚Тога it on heap 


поуе.1 (CA7),AppleMHCA5) 
тоуе.1 (CA7),-CAT) 


jcopy handle for future ref. 
;dup handle for next 2 traps 


cir.w -CAT) Р 

-Inser tMenu 

move.] *9'DRVR',-CATD jget desk accessories 
—AddResMenu ааа to Apple Menu 
clr.1 -(АТ) ,Space for next handle 
move.w "FileM,-CAT) ¿File menu ID 
-GetRMenu ;load it on heap 
поуе.1 (CA7),FileMHCA5);copy handle for future ref. 
clr.« -(АТ) ; 

-Inser tMenu 

clr.1 -САТ7) space for next handle 
move.w "EditM,-CA7T) jEdit menu ID 
-GetRMenu ;loed it on heap 


move.| (CA7),EditMHCA5); copy handle for future ref. 


сігін -САТ) ; 
-Inser tMenu 
clr.) -(GT7) ;врасе for next handle 


move.w 85С51М,-САТ) ;SCSI menu ID 

-GetRMenu ; load it on heap 

поуе.1 (А72,5С51МНСА5); сору handle for future ref. 
сігін -САТ) 

-Inser Мели 


_DrawMenuBar 
rts 


ENDPROC 


; PROCEventLoop 


; This is where we process our events. Not much happening 
; except some jump tables. We only process mouse down events 


; end system events. А11 others ignored. 


EventLoop PROC 


EXPORT 
IMPORT (DownMouse ,DownKey, Update, Activate): CODE 


Sys temTask 

clr.w -САТ) 

move.w ®EventMask,-CA7) 
pea EventRec(A5) 


; Note we unhighlight the menu only in the event loop so that 
; long opporations like formating leave the menu bar selected 
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> until they have completed. 


clr.w -САТ) 
-HiLiteMenu 
_GetNextEvent 


move.w (А72%,00 
cmp.w — "2,00 
beq.s EventLoop 


;booleen for is there an event 
jif no event, loop back 


поуеа.1 80 AQ ;clear register for jumptable 

move.w EventRec.What(A52,A8  ;get type of event 

adda.) А0,А0 jmultipy by 2 as offset table 
contains word length entries 

lea JumpTable,A1 

adda.) А1,А0 

adda.w (А0),А1 


,add offset to table address 
,add offset for proc to table addr 


jmp (А1) ,jump to procedure 
Jump Tab le 
DATAREFS RELATIVE 


. 
7 
. 
2 
7 
* 
4 


dc.w — EventLoop-JumpTable jevent 80 - null event 


іст  DownMouse-JumpTable jevent #1 - mouse-down 
іст X EventLoop-JumpTeble ,event #2 - mouse-up 
оси X EventLoop-JumpTable ,event 83 - key-down 
dc.w X EventLoop-JumpTeble ,event #4 - key-up 
dc.w  EventLoop-JumpTable event #5 - auto-key 
сн — EventLoop-JumpTable event 86 - update 
dc.w  EventLoop-JumpTable event #7 - disk- inserted 
dc.w — EventLoop-JumpTable event 88 - activate 
оси — EventLoop-JumpTable event 89 - n.a. 

dc.w X EventLoop-JumpTable event 810 - network 
dc.w — EventLoop-JumpTeble ;event #11 - device driver 
dc.w —X EventLoop-JumpTable ;Appl event #1 

dc.w X EventLoop-JumpTable ;Appl event 82 


dc.w  EventLoop-JumpTable 
dc.w  EventLoop-JumpTable 
ENDPROC 


Қор! event 83 
Қор! event 84 


PROCDownMouse 


Procedure for handling mousedown events and figuring 
out which routine is used to handle the event. 


DownMouse PROC Entry 


IMPORT (MenuBar , SysProc?:CODE 


clr.w -САТ) 
move.1 EventRec.PointCA5), -CAT) 
pea Window(A5) 
FindWindow 
поуеа. 1 80 A0 
move.w (АТ)+,А@ 
adda. 1 Аб,Аб 


¿clear register 

рор region number for mouse down 
jmultiply by two as offset 

;teble has word entries 

lea MouseTable,A1 
edde.] А1,А0 

adda.w (А0),А1 


‚ада address of table to offset 
‚ада offset of proc to table addr 


jmp (А1) ;jump to proc address 
; Offset table for mouse down events. 
MouseTable 

DATAREFS RELATIVE 


dc.w — EventLoop-MouseTable jin desk 


dc.w  MenuBar-MouseTable зіп menu ber 

dc.w — SysProc-MouseTeble jin system window 
dc.w — EventLoop-MouseTable jin contents region 
dc.w X EventLoop-MouseTeble jin drag region 
dc.w — EventLoop-MouseTable зіп grow region 
dc.w X EventLoop-MouseTable jin go away region 


ENDPROC 


; PROCMenuBar 


Subroutine for jumping to the correct menu. Put the menu 
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; number in А1 and the item number in A2. This proc finds 
; Out which menu item was selected, calculated the correct 
; eddress to jump to and jumps there. 


MenuBar PROC ENTRY 


IMPORT CQuitProc,UndoMI,CutMI,CopuMI,PasteMI2:CODE 

IMPORT CAppleMProc,SelAddrProc, PeramProc,EDef ectProc): CODE 

IMPORT (FDefectProc,FormatProc,MSenseProc,ResetProc) : CODE 

IMPORT CClearMI2:CODE 

clr.w -(АТ) ,space for longint from menu 

тоуе.1 EventRec.PointCA5),-CA7) 

-MenuSelect ,get menu selected 

movea. 1 #0,А1 ;cleer Al 

movea.1 80 А2 jclear A2 

move.w (А72%,А1 jmenu id into Al 

move.w CA7)+,A2 jmenu item into A2 

cmpa.w &0,А1 jmovea doesn’t set cond. codes 

beq eventloop jif menu 10-0 get next event 

ѕире.1 *AppleM+1,Al ,convert menu id into menu 8 
6.0. File menu becomes 0 

cmpa.w "$FFFF,A1 jwas it the apple menu 

beq AppleMProc ;yes, so go handle event 

suba.] &1,А2 jcorrect index (ist item = 0) 

edda.1 A1,A1 ;A1*2; table has word entries 

edda.1 A2,A2 ;А2%2; table has word entries 


; Now calculate address to jump to by using the values in 
; the offset tables. 


lea 
adda. 1 


adda .w 


adda. | 


adda.w (A2),A0 


MenuTable, Ад 

Ад,А1 j;this gives address of 
;correct offset in MenuTable 

(A12,A0 ;А@ now contains the address 


ОҒ the correct ItemTable 
A0,A2 ;get entry in ItemTable 
‚аба offset at this entry to 
,eddress of ItemTable 


jmp (A0) jand jump to it! 
; Offset table for each menu. 
MenuTable 
DATAREFS RELATIVE 
dc.w FileMTable-MenuTable 
dc.w EditMTable-MenuTable ;in system window 
dc.w SCSIMTable-MenuTable jin contents region 


; ItemTables 


; Offset table for each item in each menu. 


FileMTable 
dc.w 
EditMTable 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 


SCSIMTable 
dc.w 
dc.w 
dc.w 
dc.w 
dc.w 


ENDPROC 
;PROC SysProc 


QuitProc-FileMTable 
UndoMI-EditMTable 


0 

CutMI-Edi tMTable 
CopyMI-Edi tMTable 
PasteMI-EditMTable 
ClearMI-EditMTable 


SelAddrProc-SCSIMTable 
ParamProc-SCSIMTable 
EDefectProc-SCSIMTable 
FormatProc-SCSIMTable 
Rese tProc-SCSIMTable 


Mouse down in а desk accessory. Go call _SystemClick. 


SysProc 


3 6 


PROC ENTRY 


IMPORT (CEventLoop):CODE 


pea EventRecCA5 ) 
поуе.1 WindowCA5),-CA7) 
system lick 

jmp EventLoop 
ENDPROC 


;PROC QuitProc 


Procedure for quitting program. 
QuitProc PROC ENTRY 


-ExitToShe11 
ENDPROC 


;PROC UndoMI 


* Procedure to handle selection of the “Undo” menu item when а 
; desk accessory controls the active window. 
UndoMIPROC ^ ENTRY 


clr.w -CAT) 
move.w %0,-(АТ) 
-SysEdit 

adda.] 82 А7 

jmp EventLoop 
ENDPROC 


;PROC CutMI 


Procedure to handle selection of the “Cut” menu item when a 
; desk accessory controls the active window. 
CutMI PROC ENTRY 


clr.w -САТ) 
move.w 92,-CATD 
-SysEdit 


. move.w (AT)*,DO 


jmp EventLoop 
ENDPROC 


;PROC СоруМІ 


Procedure to handle selection of “Copy” menu item when а 
; desk accessory controls the active window. 
CopyMIPROC ЕМТКҮ 


clr.« (АТ) 
move.w %3,-CA7) 
-SysEdit 

move.w (АТ)+,0@ 
jmp EventLoop 
ENDPROC 


;PROC PasteMI 


f Procedure to handle selection of “Paste” menu item when 
; desk accessory controls the active window. 
PasteMI PROC ENTRY 


clr.« -—(АТ) 
move.w %4,-CA7) 
-SysEdit 

move.w САТ )+,00 
jmp EventLoop 
ENDPROC 


;PROC ClearMI 


Procedure to handle selection of “Clear” menu item when 
; desk accessory controls the active window. 
ClearMI PROC ЕМТВҮ 


cir.w -CAT) 
move.w %5,-CA7) 
-SysEdit 

move.w (CA7)+,D@ 
jmp EventLoop 
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ENDPROC 
PROC AppleMProc 


entry, A2 has the item number of the menu item that was 


; 
; This procedure handles menu events in the Apple menu. On 
selected. 


AppleMProcPROC ENTRY 
IMPORT (CDAName,QuickDraw):DATA 
IMPORT CAboutProc,EventLoop):CODE 


стра.1 *AboutItem,A2 ;“About U2 Formatter” selected? 


beq AboutProc ез, go put up dialog 
; A desk accessory was selected, go install it. 
move.] QuickDraw.thePortCA5), MyPor t (Ab) ;save our 
port 
поуе.1 AppleMHCA5),-CA7) ;push handle for apple menu 
move.w A2,-CAT) ;push item number hit 
pea DANameCA5 ) jpush space for DA name 
-GetItem ;get 0А name 
clr.w -CAT) j;space for driver reference & 
pea DANameCA5 ) ;раѕѕ DA name 
-OpenDeskAcc ;ореп DA 


edda.] #2,АТ 


move.) MyPortCA5),-CA7) restore our port 
-SetPort 

jmp EventLoop 

ENDPROC 


; PROC AboutProc 


д 
; This procedure puts up our about U2 Formatter dialog box. 
AboutProc PROC ENTRY 

IMPORT (ButtonHit, QuickDraw):DATA 

IMPORT CEventLoop,DefButton): CODE 


clr.1 -САТ) space for pointer to dialog 
move.w "AboutRN, -CA7) ; About dialog resource number 
pea DialogBuf f СА5) ;pess address of dialog buffer 
поуе.1 8-1,-(АТ7) jbring dialog window to front 
-GetNewDialog 


поуе.1 CA7),DialogPort(A5) ;Ѕауе ptr to dialog rec 
jhote: pointer still on 
;stack for .SetPort trap 

-SetPort 

lea DialogBuffCA5),A4 ;раѕѕ address of dialog buffer 

jsr Def Button 


NotYet 
clr.1 -(7) juse standard filter proc 
pea But tonHitCA5) jaddr of storage for item hit 
-ModalDialog 
cmpi.w ®1,ButtonHitCA5) — ;which item hit? is it “ок”? 
bne NotYet ;no so loop back 
поуе.1 DialogPort(A52,-CA7)  ;pass ptr to dialog rec 
-CloseDialog 
jmp EventLoop 
ENDPROC 


PROC DefButton 


button in а modal dialog. It gets passed the address of our 
dialog. It then gets the rectangle for the first item and 


; 
This procedure draws а rounded rectangle around our default 
f draws a rounded rectangle around it. 


DefButton PROC EXPORT 
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д 


Wwe We We We We We We We We We We We We 


movem. 1 00-02/А0-А4,-(АТ) ;save registers 


First we get the rectangle for item 1. 


тоуе.1 A4,-CAT) ;push pointer for dialog 
move.w !1,-CAT) ;push item number 

pea ItemTypeCA5) addr of space for item type 
pea ItemHandle(CA5) ,eddress of space for handle 
pea ItemRect(CA5) jaddress of space for rect 
-getDItem 

move.w €" 3,-CAT) ;chenge pensize to 3X3 

move.w 83,-(АТ) 

-PenS ize 


реа ItemRectC(A5) ;тәке button smaller; 811 edges 


move.w 9-4,-CAT) jmoved in by 4 pixels 

move.w 8-4 -(АТ) 

-InsetRect 

pea ItemRect(A5) — ;drew boarder for default button 
move.w #16,-CA7) ;curvature is 16 pixel in both 
move.w %16,-CA7) directions 

-FremeRoundRect 

тоуем. 1 (A72*,D0-D2/A0-A4 ;restore registers 

rts 

ENDPROC 


PROC RadioHiLite 


This procedure selects the radio button that was chosen and 
deselects the radio button that was previously selected. 
receives the old selected button in 00 and the new one in 


01. It also receives the address of the dialog buffer in M 


If this is the first time the procedure is being called 
for а given dialog box, it should be passed zero in 00 
so that it doesn’t try to deselect a radio button that 
is not selected. 

This procedure also checks to see that the button that was 


chosen was not the one that was already selected. If it is, 


it doesn’t deselect it. 


RadioHiLite PROC EXPORT 


помет. 1 D@-D2/D6-D7/AG-A4,-CA7) ;ѕауе registers 


move.w 00,06 з томе radio button values to register 


move.w D1,D7 ; that wont be trashed by traps 


тоуе.1 А4,-САТ)  ;get rectangle for radio button 
move.w D7,-CAT) 

pea ItemTypeCA5 ) 

pea ItemHandleCAb) 

pea ItemRect(A5) 
_getDI tem 


Duplicate top left hand point of rectangle into bottom right 


point of rectangle. They are now the same. Now add a 
different constant to each so the circle in this rect 
is right in the middle of the radio button. Then invert 
this oval so it changes from white to black. 

move.1 ItemRectCA5), I temRect+4(A5) 

addi.1 %$00070005, ItemRect(A5) 

addi.1 #$0000000В, I temRect+4(A5) 

pea ItemRect(A5) 

_Inver t0val 


cmp.1 D6,D7 ;is the radio button the same one that 
beq Done ;was highlighted last time? If so, 
jwe are done. 


tst.1 06 ;is this the first time called? 
beq Done ;if so, 06=0 and we must quit 
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; pointer to the string on the stack. 


; Repeat the opporation for the old radio button, the one that add.1  "$1000,D3 ;add offset to error® to get cause! 
; was previously highlighted. This time _InvertOval will сіг.1 -САТ) ,space for handle 
; chenge it from black to white. move.] "'STR *,-САТ) ;type of resource 
поуе.1 A4,-CATD move.w D3,-CA7) ;resource number 
move.w D6,-CA7) -Ge tResource ;get resource handle 
pea ItemTypeCA5) move.] (А72%,Ай jpop handle into AØ 
pea ItemHandleCA5) move.1 САЙ), -САТ) ,dereference handle апа push ptr 
pea ItemRectCAb) 
-getDItem clr.b StrBuff4(A5) ;make last string empty 
поуе.1 ItemRectCA5), ItemRect*4CAb) pea StrBuff4CA5) ;рәѕѕ pointer to empty string 
addi.1 *$00070005,ItemRect(A5) -PeranText 
addi.1 *$0000000B,ItemRect*4CA5) move.w 9"133,-CAT) ;resource number for dialog 
pea ItemRectCA5) clr.1 -CAT) ,use standard filter proc 
-Ілуегі0у81 clr.w -САТ) 
-NoteAlert 
Done clr.w (АТ) 
movem.1€A72*,D0-D2/D6-D7/A0-A4  ;restore registers 
rts jmp EventLoop jreturn to the event loop 
ENDPROC 
ENDPROC 


; PROC CountOff 
PROC ErrorProc ; 


f This procedure produces a delay equal to the number of ticks 


д 
7 
; This procedure puts up an error dialog box. The dialog tells ; in the long word passed in 00. 
; what the last SCSI command or trep was, what error occurred 
; and а possible explanation. А11 text is in STR resources. CountOff PROC EXPORT 
; Trap names are given the resource number: “АХ00” where X is movem.100-D3/A0-A1,-CAT) ;save the registers 
; the routine selector used by the SCSI Manager СІМ, IV-295). 
; SCSI commands ere given the resource number: “X00” where X move.1 00,03 ,move our value into a register that 
; is the SCSI op code. These values are all in the ;wont be trashed by the traps 
; FormatEqu.a file. Resource number clr.1 -С(АТ) ,Space for the current tick count 
; for errors are of the form “ААХХ” for traps where ХХ is -TickCount 
; the OSErr returned from the trap, or *10XX^ for SCSI edd.| САТ)+,03 X ;add our delay to the current tick 
; commands, where XX is the SCSI error reported ;count, this is when we stop 
; by -SCSIComplete in the ;waiting. 
; status parameter. Resource numbers for the “Most Probable 
; Cause” strings ere “BAXX” for traps and “20ХХ” for SCSI ; Our loop to see if we have gone past the tick count we are 
; Commands. ; waiting for. 
NotYet 

ErrorProc PROC EXPORT сіг.1 -(АТ) ,space for % of ticks since reboot 

IMPORT (Last. Cmd, Res, CompStat , CompMsg) :DATA _TickCount 

стр.1 САТ)+,03 ;іѕ this as big as the number we are 

; Get res number for last command string and place a pointer ,waiting for? 
; to the string on the stack. bgt NotYet ;if not, then repeat loop 

clr.) 04 ;р1асе no. for last command іп D4 

move.w Last Cmd(A5),D4 movem.1 (А72%,00-03/А0-А1 ;restore registers 

151.1 88/04 ;multipy by $100. ris 

clr.1 -(АТ) ;space for handle ENDPROC 

move.] #/’STR ‘,-CA7) ;іуре of resource 

move.w D4,-CA7) ,resource number 

~GetResource jget handle last command string PROC UnHiLite 


move.] (А72%,А0 рор handle into Ag 


тоуе.1 (А0),-(АТ) dereference handle & push ptr This procedure unhighlights an item in a dialog box to show 


that it cannot be selected. It receives the address of the 


; Get resource number for error string and place a pointer dialog record in A4 and item number to be unhighlighted in 
00. 


; to the string on the stack. 


we We We Wo We We 


clr.1 D3 
move .w Res(A5),D3 jif there was no OSError, Res=0 UnHiLite PROC EXPORT 
bne ErrorInTrap 2АҒ Res = 0, error in SCSI cmd тоует.1 00-02 /А4-А1,-С(АТ) ;save the registers 
move.w CompStatCA5),D3;SCSI error into 03 
edd.w %$1000,03 ,add offset for SCSI cmd error move.1 A4,-CA7) ;деї the item rect for the item 
bre.s Continue move.w D0,-CAT)  ;number that we were passed 
ErrorInTrep pea ItemTypeCA5) 
edd.w *§AAG0,D3 ,edd offset OS trap error pea ItemHandle(A5) 
Continue pea ItemRectCA5) 
clr.1 -CAT) ,Space for handle -getDItem 
поуе.1 8”5ТЕ ‘,-CA7) ;type of resource 
move.w D3,-CA7) ,resource number move.] ItemHandle(A5),-CA7) ;раѕѕ the item handle 
-GetResource зде resource handle move.w %255,-CA7) ;pass flag for unhighlighting 
тоуе.1 (А72%,А0 )рор handle into Ай -HiLiteControl 


move.] (A02,-CAT) ,dereference handle and push ptr 


movem.] САТ )+,00-02/Аб-А1 ;restore registers 
; Get resource number for probable cause string and place а rts 
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ENDPROC 


Exit 
; PROC ExtractNumb movem.1 CA72*,D0-D2/A0-A1 ;restore registers 
P rts 
; This procedure extracts number value from edit text item ENDPROC 
; in a dialog box. It gets passed item number in 00 and 
; address of the Dialog box record in А4. АЗ contains а ptr END 
; to the long where output is to be placed and D3 contains the | | 
; maximum value allowable. /* Format.r 3/1/87 Timothy Stending 

Resources for the SCSI formatting progrem.*/ 

ExtractNumb PROC EXPORT "include *Types.r" 


поуем. 1 00-02/Ай-А 1,-САТ) ;save registers 
/* These define’s used in MENU resources to disable specific 


сіг.1 САЗ) ;clear output long menu items. */ 
; Get the handle for this item number. "define AllItems 0b1111111111111111111111111111111  /* 31 
поуе.1 А4,-(АТ) spass dialog record pointer flags */ 
move.w 00,-(А7) ;pass item number "define Menul tem 1 000000 1 
pea ItemTypeCA5) def ine Menul tem2 00000 10 
pea ItemHandleCA5) "def ine MenuItem3 0b00 100 
pea ItemRect(A5b) def ine MenuItem4 060 1000 
-getDItem "def ine MenuItemb Øb 10000 
; Get the text from that dialog item. Move text into resource ‘MENU’ (128, “Apple”, preload,nonpurgeable) ( 
StrBuff 1. 128, textMenuProc, 
тоуе.1 ItemHandle(A5),-CAT) AllItems & "MenuItem2, /* Disable item 82 */ 
pea StrBuf f 1(А5) enabled, apple, 
-GetIText 
“About Format’, 
с1г.1 DØ ;get length of text out of first noicon, nokey, nomark, plain; 
move.b StrBuff 1(A52,DO;byte and place it in DØ s 
ble Exit ;if length is Ø, we are done. noicon, nokey, nomark, plain 
; Loop to remove 811 characters that aren't numbers. 01 is the ; 
; index for the position being tested. 02 is the index for the resource ‘MENU’ (129, “File”, preload,nonpurgeable) ( 
; lest valid position. 129, textMenuProc, 
lea _ StrBuff1(A52,A8 — ;initialize Ай to point to al lEnabled, 
string enabled, “File”, 
поуеа.1 #1,D1 
moveq. 1 #1,D2 “Мі, 
noicon, покеу, nomark, plain 
Loop: 
cmp.b 8%" ,(А0,01.) ;test next character ); 
blt NotNumb resource ‘MENU’ (130, “Edit”, preload,nonpurgeable) ( 
cmp.b  */9',C(A0,D1.w) 138, textMenuProc, 
bgt NotNumb AllItems & ^KMenuItem! | MenuItem2), /Х Disable items 
#1 & "2 */ 
cmp.1 01,02 ;if indeces ere same, no move is enabled, *Edit^, 
beq NoMove ,hecessary 
move.b (A0,D1.w2,CA0,D2.w)  ;move character "Undo", 
noicon, "Z^, nomark, plain; 
NoMove: к=. 
addq.1 81,01 ;increment both pointers as last noicon, nokey, nomerk, plain; 
addq.1 81,02 ;character was а number “Cut”, 
cmp.w 01,00 ;reached the end of string? noicon, “Х”, nomark, plain; 
bge (оор sno “Сору”, 
бга Convert ,yes noicon, *C^, nomark, plain; 
“Paste”, 
NotNumb noicon, “V”, nomark, plain; 
eddq.w #1,D1 ;only increment test pointer “Clear”, 
cmp.w D1,DØ reached the end of string? noicon, nokey, nomark, plain 
bge (оор sno ) 
bre Convert  ;уез ); 
resource ‘MENU’ (131, “SCSI”, preload,nonpurgeable) ( 
Convert: 131, textMenuProc, 
subq.1 51,02 ;make D2 into count byte al Enabled, 
move.b D2,CAQ) _ ;count byte into byte 1 of string enabled, “SCSI”, 
-Str ingToNum ;convert to hex value ( 
поуе.1 DO,CA3) ;move result to output "Select Address", 
noicon, nokey, nomark, plain; 
Default “Parameters”, 
cmp.1 (A3),D3 ;іѕ result greater than allowable noicon, nokey, nomark, plein; 
оде X Exit ;no, we can exit "Enter Defects”, | 
поуе.1 03,(АЗ) ;yes so use default value instead noicon, nokey, nomark, plain; 
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“Format”, 

noicon, nokey, nomark, plain; 
“Reset”, 

noicon, nokey, nomark, plain 


resource ‘DLOG’ (128, “About Format”, preload,nonpurgeable) ( 
(106, 106, 290, 406), 
dBoxProc, visible, noGoAway, 0x0, 128, *" 


); 
resource ‘DITL’ (128, preloed,nonpurgeable) ( 


/* 1 */ (141,202, 161,273), 
button ( 
enabled, 
"OK" 


); 
/* 2 */ (15,27,41,214), 
steticText ( 
enabled, 
“A formatting program for MacTutor™ 


д 
/* 3 */ (46,97,69,204), 
staticText ( 
enabled, 
“py Tim Standing” 


/* Author Item */ 


д 
/* 4 */ (81,46, 101,260), 
steticText ( 
enabled, 
“For help with this program see” 


/* 5 */ (101,46,119,260), 
staticText ( 
disabled, 
“the June ’87 issue of MacTutor "^ 


д 
/* 6 */ (141,31, 156, 172), 
staticText ( 
enabled, 
“0 1987 Tim Standing" 


) 

); 

resource ‘DLOG’ (129,^"Select Address",preloed,nonpurgeeble) ( 
(54,99,295,391), 


dBoxProc, visible, noGoAway, 0x0, 129, "" 
resource ‘DITL’ €129,preload,nonpurgeeble) ( 


/* 1 */ (195,75,215, 135), 
button ( 
enabled, 
“Select” 


М 
/* 2 */ (195, 168,215,226}, 
button ( 
enabled, 
“Cancel” 


); 
/* 3 */ (55,15,15, 115), 
RadioButton ( 


enabled, 
“ngs 


) 
/*4*/ (85,75, 105, 115), 
RedioButton ( 


enabled, 
"11^ 


); 
/ж 5 */ (115,75, 135, 115), 
RadioButton ( 


enabled, 
“noe 


40 


» 
/* 6 */ (145,75, 165, 115), 
RedioButton ( 


enabled, 
“43” 


); 
/* 1 */ (55,115,15,215), 
RedioButton ( 


enabled, 
anga 


); 
/% 8 */ (85,175, 105,215), 
RadioButton ( 


enabled, 
nie 


); 
/* 9 */ (115,175, 135,215), 
RedioButton ( 


enabled, 
&6> 


); 
/% 10 */ (145, 175, 160,215), 
RedioButton ( 


disebled, 
ang” 


); 
/* 11 */ (160, 175, 175,285), 
staticText ( 
disebled, 
“(Mac’s Address)" 


/* 12 */ (12,35,30,258), 
staticText ( 
disebled, 
“Please select the SCSI address of” 


/* 13 */ (27,35, 47, 263), 
staticText ( 
disabled, 
“the hard disk you wish to format:” 


) 

); 

dedo "DLOG^ (130, "Enter Parameters^,preload,nonpurgeable) 
(33,43,330, 469), 


dBoxProc, visible, noGoAway, 8x0, 130, "^ 


resource ‘DITL’ C130,preload,nonpurgeable) ( 


/* 1 */ (260,345,280,405), 
button ( 
enabled, 
“оқ” 


button 
enabled, 
“Cancel” 


); 
/* 3 */ (73,115,93, 158), 
RadioButton ( 
enabled, 
iri? 


); 
J* 2 *%/ (230,245, 250,405), 


); 
/* 4 */ (13,115,93,219), 
RedioButton ( 
enabled, 
94251? 


); 
/* 5 */ (13,235,93,278), 
RedioButton ( 
enabled, 
«3: 1^ 
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); 
/* 6 */ (13,295,93,338), 
RadioButton ( 
enabled, 
“4:1 


); 
/% 1 *J (103, 135, 123,402), 
RadioButton ( 
enabled, 
“3.0 mSec (ST506-Nonbuffered Seeks)" 


— 
ж 


); 
8 */ (123, 135, 143,375), 
RadioButton ( 
enabled, 
“28 uSec (ST412-Buf fered Seeks)” 


); 
/% 9 */ (143, 135, 163,415), 
RadioButton ( 


enabled, 
* 12 uSec (Pseudo ST412-Buffered Seeks)” 


); 
x/ (173,170, 188,222), 
EditText ( 
disabled, 
"0% 


/* 1 


/* 1 


Gree 


); 
*/ (203, 170,218,222), 
EditText ( 
disebled, 


«g^ 


); 
/* 12 */ (233,245,248,297), 
EditText ( 
disebled, 
"g^ 


); 
/* 13 */ (263,245,278,297), 
EditText ( 
disabled, 
"g^ 


); 
/* 14 */ (12,44,21,314), 
StaticText ( 
disebled, 
“Please enter the parameters for the disk that” 


); 
/* 15 */ (27,44,43,390), 
StaticText ( 
disabled, 
“you wish to format. Enter a zero for each 
unused” 


); 
/* 16 */ (43,43,58,303), 
StaticText ( 
disabled, 
*field. All numbers are decimal." 


); 
/* 17 */ (73, 15,88, 107), 
StaticText ( 
disebled, 
“Inter leave: * 


); 
/* 18 */ (103,15, 118, 130), 
StaticText ( 
disabled, 
“Step Pulse Rate:” 


); 
/* 19 */ (173, 15, 188, 144), 
StaticText ( 
disabled, 
“Number of Heads:" 


? 
J* 20 */ (203, 15,218, 162), 
SteticText ( 
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disabled, 
“Number of Cylinders:” 


/% 21 */ (233, 15,248,239),. 
StaticText ( 
disabled, 
"Reduced Write Current Cylinder: ” 


); 
/* 22 */ (263,15,278,240), 
SteticText ( 
disebled, 
“Write Precompensation Cylinder : ” 


) 

); 

resource ‘DLOG’ (131,’Enter Defects",preload,nonpurgeeble) ( 
(31, 16,331,496), 


dBoxProc, visible, noGoAway, 9x9, 131, *" 
Н 
resource ‘DITL’ (131,preload,nonpurgeable) ( 


/* 1 */ (10,400,30,460), 
button ( 
enabled, 
"OK" 


button 
enabled, 
“Моге” 


); 
/* 2 */ (40,400, 68, 460), 


); 
/* 3 */ (10,400,90,460), 
button ( 
enabled, 
“Cancel” 


); 
/* 4 */ (120,50, 135,85), 
EditText ( 
enabled, 
0” 


); 
/% 5 */ (120,115,135,140), 
EditText ( 
enabled, 
"g^ 


5 
/% 6 */ (120, 160, 135,210), 
EditText ( 
enebled, 
aga 


); 
/* 1 */ (150,50, 165,85), 
EditText ( 
enabled, 
nga 


); 
/% 8 %/ (150, 115, 165, 140), 
EditText ( 
enabled, 
«g^ 


); 
/* 9 */ (150,160, 165,210), 
EditText ( 
enabled, 
«g^ 


); 
/* 10 */ (180,50, 195,85), 
EditText ( 
enabled, 
«g^ 


); 
/% 11 */ (180, 115, 195, 140), 
EditText ( 
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enabled, 
«g^ 


) А 
/% 12 */ (180,160, 195,210), 
EditText ( 
enabled, 
"g^ 


) è 
/* 13 */ (210,50,225,85), 
EditText ( 
enabled, 
"g^ 


) . 
/* M */ (210, 115,225, 140), 
EditText ( 
enabled, 
"g^ 


); 
/* 15 */ (210,160,225,210), 
EditText ( 
enabled, 


«g^ 


); 
/ 16 */ (240,50,255,85), 
EditText ( 
enabled, 


«g^ 


); 
/* 17 */ (240,115,255, 140), 
EditText ( 
enabled, 
"g^ 


); 
/* 18 */ (240,160,255,210), 
EditText ( 
enabled, 
nga 


); 
/* 19 */ (210,50,285,85), 
EditText ( 
enabled, 
ЫЫ 


); 
20 */ (270,115,285, 140), 
EditText ( 
enabled, 


"g^ 


— 
* 


) { 
/* 21 */ (270, 160,285,210), 
EditText ( 
enabled, 
"g^ 


); 
/% 22 */ (120,200, 135,325), 
EditText ( 
enabled, 
"g^ 


); 
/ 23 */ (120,355, 135,380), 
EditText ( 
enabled, 


nga 


); 
/* 24 */ (120,400, 135,450), 
EditText ( 
enabled, 
"g^ 


); 
/% 25 %/ (150,290, 165,325), 
EditText ( 
enabled, 
"g^ 


}: 
/* 26 */ (150,355, 165,380), 
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EditText ( 
enabled, 
«g^ 


); 
/% 21 */ (150,400, 165,450), 
EditText ( 
enabled, 


20” 


); 
/* 28 */ (180,290, 195,325), 
EditText ( 


) 5 
/% 29 %/ (180,355, 195,380), 
EditText ( 
enabled, 


0% 


); 
/% 30 */ (180,400, 195,450), 
EditText ( 
enabled, 


«g^ 


}; 
/* 31 */ (210,290,225,325), 
EditText ( 
enabled, 
"g^ 


); 
/* 32 %/ (210,355,225,380), 
EditText ( 
enabled, 
"g^ 


); 
/* 33 */ (218, 480,225, 450), 
EditText ( 
enabled, 
"g^ 


) 
/% 34 */ (240,290,255,325), 
EditText ( 
enabled, 


«g^ 


); 
/* 35 */ (240,355,255, 380), 
EditText ( 
enabled, 
"0% 


); 
/* 36 */ (240,400,255,450), 
EditText ( 
enabled, 
“0% 


); 
/% 37 %/ (210,290,285,325), 
EditText ( 
enabled, 


«g^ 


); 
/% 38 */ (270,355,285,380), 
EditText 
enabled, 
"g^ 


); 
/ 39 */ (278, 400,285, 450), 
EditText ( 
enabled, 
aga 


J5 

/% 40 */ (10, 15,25,375), 
StaticText ( 
disebled, 


“Please enter the list of defects that came with 


your ” 
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); 
/ 41 */ (25,15,40,315), 

StaticText ( 

disabled, 

“disk drive. Enter the Head #, Cylinder 8, and 
Bytes” 


д 
/* 42 */ (40,15,55,375), 
StaticText ( 
disabled, 
“From Index (BFI) value for each defect. Enter’ 


); 

/* 43 */ (55, 15,708,370), 
StaticText ( 
disebled, 


“defects in order of increasing cylinder #. If you” 


д 
/* 44 */ (70, 15,85,370), 
StaticText ( 
disabled, 
“nave more than 12 defects, click on the More 
Button.” 


); 
J* 45 %/ (120, 10, 135,45), 
SteticText ( 


disebled, 
“1,” 


); 
/* 46 */ (150,10, 165,45), 
StaticText ( 


disebled, 
ng.” 


); 
/ 47 */ (180, 10, 195, 45), 
SteticText ( 


disebled, 
13.2 


); 
/* 48 */ (210,10,225,45), 
StaticText ( 


disebled, 
4.2 


); 
/ 49 */ (240,10,255,45), 
StaticText ( 


disebled, 
«95.2 


); 

/* 50 */ (276, 16,285, 45), 
SteticText ( 
disebled, 

*86.^ 


); 
/* 51 */ (120,250, 135,285), 
SteticText ( 


disebled, 
ny. ^ 


; 
/* 52 */ (150,250, 165,285), 
SteticText ( 


disebled, 
"ag. ^ 


); 
/* 53 */ (180,250, 195,285), 
StaticText ( 


disebled, 
«9:2 


| ); 

/* 54 %/ (210,250,225,285), 
StaticText ( 
disebled, 

“10:” 


) 
/* 55 */ (240,250,255,285), 
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StaticText ( 


disabled, 
”%11:% 


); 

/ 56 %/ (270,250,285,285), 
StaticText ( 
disabled, 
^112:^ 


); 

/* 57 */ (95,30, 110, 100), 
StaticText ( 
disabled, 
“Cylinder : * 


д 
/ 58 */ (95,110, 110, 155), 
StaticText ( 
disebled, 
“Head: ^ 


J; 

/* 59 */ (95, 165, 110,200), 
SteticText ( 
disebled, 

"BFI:” 


P 

/* 60 */ (95,270, 110,340), 
StaticText ( 
disabled, 
"Cylinder : ” 


/* 61 */ (95,350, 110,395), 
StaticText ( 
disabled, 
“Head: ^ 


p 

/* 62 */ (95,410,110,445), 
StaticText ( 
disebled, 
"BFI:” 
) 


) 

resource ‘ALRT’ (132, ^Format Alert^,preload,nonpurgeable) ( 
(100, 100,250, 400) , 
2 


Cancel, visible,2; 
Cancel ,visible,2; 
Cancel ,visible,2; 
ны с 


resource ‘DITL’ (132,preload,nonpurgeable) ( 


/* 1 */ (115,75, 135, 135), 
button ( 
enabled, 
“OK? 


}; 
/* 2 */ (115, 165, 135,225), 
button ( 
enabled, 
“Cancel” 


д 
/* 3 */ (30,80,45,200), 
StaticText ( 
disabled, 
“Do you really want to format” 


4 


/ 4 %/ (45,80,60,290), 
StaticText ( 
disabled, 

“disk drive 8507 It will erase” 


); 


43 


/* 5 */ (60,80,75,290), 
Statictext ( 
disebled, 

“all the files on this volume.” 


) 
resource 'ALRT^ (133,preload,nonpurgeable) ( 
(50, 40, 300, 460), 
133, 
( /* array: 4 elements */ 
/* (1) */ 
OK, visible, sound; 
/* 12] */ 
OK, visible, sound]; 
/* [3] */ 
OK, visible, soundi; 
/* (4] */ 
OK, visible, sound! 


); 


resource 'DITL^ C133,preload,nonpurgeeble) ( 
/* array DITLarrey: 8 elements */ 
/* (1) */ 
(213, 180, 233, 240), 
Button ( 
enabled, 
"OK? 


); 
/* (2] */ 
(19, 92, 34, 267), 
SteticText ( 
enabled, 
“A SCSI error has occurred!” 


); 
/* [3] */ 
(70, 15, 85, 251), 
StaticText ( 
disebled, 
“SCSI command or trap that failed:"^ 


/* [4] */ 

(85, 35, 99, 200), 

StaticText ( 
disabled, 


naga 


); 
/* [5) */ 
(115, 15, 130, 125), 
StaticText ( 
disabled, 
“Type of еггог:” 


/* [67] */ 

(130, 35, 145, 290), 

StaticText ( 
disebled, 


wa 17 


); 
/* [Т] */ 
(160, 15, 175, 200), 
StaticText ( 
disabled, 
“Most probable cause: ” 


д 
/* [8] */ 
(175, 35, 190, 405), 
StaticText ( 
disabled, 


”-2% 
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resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


resource 


‘STR ° ($4009, preload, nonpurgeable) ( 
* SCSIReset.^ 


‘STR ” ($A108,preload,nonpurgeable) ( 
* SCSIGet.” 


‘STR * ($A200,preload,nonpurgeable) ( 
* SCSISelect."^ 


‘STR ' ($4300, preload, попригдеаб1е) ( 
* SCSICommend."^ 


‘STR ' ($4400 ,preloed,nonpurgeeble) ( 
“_SCSIComplete. ” 


‘STR ' ($4600,preload,nonpurgeable) ( 
* SCSIWrite.^ 


‘STR ' ($220, preload, nonpurgeable) ( 
“Test Unit Ready.” 


‘STR ' ($409, preload, nonpurgeable) ( 
“Format Unit.” 


‘STR * ($1500,preload,nonpurgeable) ( 
“Mode Select.” 


‘STR ‘ ($1003, preload, nonpurgeable) ( 
“Write Fault.” 


‘STR ' ($ 1804, preload, nonpurgeable) ( 
“Drive not ready.” 


‘STR ' ($1028, preload, nonpurgeable) ( 
“Command not implemented." 


‘STR * ($1024 preload, nonpurgeable) ( 
“Bad parameter passed to controller.” 


‘STR * ($4402, preload,nonpurgeable) ( 
“SCSI communication error.” 


‘STR ' ($4424, preload, nonpurgeable) ( 
“Bad pseudo program.” 


‘STR * ($4405, preload, nonpurgeable) ( 
“SCSI timing error.” 


‘STR ' ($2203, preload, nonpurgeable) ( 


“Drive detects failure during power on diagnostic.” 


‘STR ' ($2004, preload,nonpurgeable) ( 


“Drive not up to speed or hardware problem." 


‘STR * ($2020, preload,nonpurgeable) ( 


“Controller does not support this command.” 


‘STR * ($2024,preload,nonpurgeable) ( 


“Defect in cylinder 0 or bad defect parameters.” 


‘STR ° ($BAO2,preload,nonpurgeable) ( 
“Wrong address or no termination.” 


‘STR ' ($8A04,preload,nonpurgeable) ( 
“Programmer error; my fault.” 


‘STR “ ($BA05,preload, nonpurgeable) ( 


“Program uses incorrect delay value for your 


controller.” 


resource ‘ALRT’ C134, preload,nonpurgeable) ( 
(100, 100, 270, 400), 


134, 


( 


/* erray: 4 elements */ 
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/* (1) */ 
OK, visible, sound]; 
/* (2) */ 
OK, visible, sound!; 
/* [3] */ 
OK, visible, sound]; 
/* (4) */ 
OK, visible, sound! 


); 


resource ‘DITL’ (€134,preload,nonpurgeable) ( 
/* array DITLerrey: 4 elements */ 


enabled, 
“OK a 


); 
/* (2) */ 
(20, 90, 35, 252), 
StaticText ( 
enabled, 
“Қо more defects can бе” 


д 
/* (3) */ 
(40, 90, 55, 263), 
StaticText ( 
disebled, 
“added to the defect list.” 


); 
/* (4) */ 
(60, 90, 75, 263), 
StaticText ( 
disebled, 
*The buffer is full. The^ 


/* [5] */ 
(80, 98, 95, 275}, 
StaticText ( 
disabled, 
“first 60 defects were used." 


) 


); 
resource ‘DLOG’ (135,preload,nonpurgeable) ( 
(131, 131, 231, 381), 
dBoxProc, 
visible, 
noGoAway, 
0x0, 
135, 


); 
resource 'DITL^ (135,preload,nonpurgeable) ( 
/* array DITLerray: 3 elements */ 
/* (1) */ 
(15, 20, 30, 230), 
StaticText ( 
enabled, 
“Now formatting SCSI disk #°9.” 


); 
/* [2] */ 
(35, 20, 50, 224), 
StaticText ( 
disabled, 
“This will take between three’ 


); 
/* (3) */ 
(55, 20, 70, 166), 
SteticText ( 
disebled, 
“and fifteen minutes." 


) 
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SCSI Formatter Insights 
Steve Brecher 
Sunnyvale, CA 

(From Letters Column Vol. 3 No. 9) 

There are some errors in the “SCSI Formatter Project, Part II" 
article in the June 1987 MacTutor, and I thought that corrections 
might be of help to readers who are implementing the project. 

(1) The status byte which is returned to the initiator (the Mac) 
by a target device (disk controller) is not a target-specific error 
code. Rather, itis a generalized result. Bit 1 setindicatesa “check 
condition," or error. Hence, a status byte value of 2 indicates that 
an error occurred, but it does not indicate the nature of the error. 
To determine the cause of the error, a Request Sense command 
must be issued to the target. Then the target will send sense data 
which specifies the nature of the error that occurred. 

This — not a bug in the SCSI Manager - is the reason that 
author Tim Standing observed a status value of 2 when an error 
occurred. This misunderstanding is reflected in the Formatter 
program code, which will not correctly diagnose or report error 
conditions. 

In sum, there are three sources of error information: (a) the 
result code returned by a SCSI Manager function, e.g., phase 
error, which indicates whether there was some problem in 
communicating with the target device; (b) the status byte which 
is returned in the low half of the VAR "stat" integer parameter of 
the SCSIComplete call, which indicates whether or not an error 
occurred; and (c) the sense data that is returned by the target in 
response to a Request Sense command, e.g., unit not ready, write 
fault, etc., which indicates the exact nature of any error that 
occurred. 

(2) Pseudo-programs, or Transfer Instruction Blocks (TIBs), 
are not part of the SCSI standard. Rather, they are an invention 
of Apple, and are found only in Apple's SCSI Manager software. 
TIBs were implemented to permit the transfer of disk file sector 
tags along with each sector of disk data; the tags and the sector 
data are at different RAM addresses and must be read/written in 
an interleaved fashion (tags, sector data, tags, sector data...). 
TIBs permit multiple sectors with tags to be read or written with 
justone SCSICmd and one SCSIRead or SCSIWrite call. While 
some existing products implement file sector tags, Apple is no 
longer supporting tags for new products, so in that sense TIBs are 
implemented only for historical reasons. 

Last, a few minor implementation notes: 

The Mac OS provides a Delay routine which can be used in 
place of Tim's CountOff subroutine. 

The Control Manager provides a SetCtl Value routine which 
can be used to alter the setting of a radio button and redraw it to 
reflect the new setting. 


Assembly Language Lab 
Icon Reader Utility 


Getting Application Icons 

Whenever I receive a number of new programs, one of the 
things I most look forward to is seeing the new icons. Normally 
this would require a trip to the Finder, but even there you can't see 
any related document icons until you open the application and 
create a file (or use ResEdit). If you don't happen to have 120k 
free on your disk, you can use this little IconApp utility to view 
application and document icons. 

Even though every application on the Desktop has an icon, 
applications that haven't been *bundled' or set up to display a 
specific icon (along with other information) take on a generic 
application icon which is stored in the Finder. Applications 
which have been bundled and have a file reference number, used 
by the Finder to associate applications with their icons (BNDL 
and FREF), can have a unique icon on the Desktop. The Finder 
copies the file's iconsinto the destkop file and keeps track of each 
icon set per each file creator tag. Thus if another applicaton is 
loaded with the same creator as a previous application, it's icon 
will change to the wrong icon on the desktop. This is why creator 
tags must be unique. Also, the deskto never forgets, soeven if you 
have a unique creator tag, it may be necessary to force the Finder 
to rebuild the desktop file by holding down the cmd-option keys 
during a re-boot. This program opens an application’s resource 
fork and displays the program’s bundled icons in a small dialog 
box. 

An icon is a quickdraw object that is defined as a small 128 
byte bitmap four bytes wide living in a small rectangle 32 by 32. 
In our program we define a bitmap to hold the icon as follows: 

iconmap: іс]  ; pointer to bit image base address 

dc.w ; integer of row bytes (4) 
dc.w ; тесі topO 
ас ;rect left 0 
dc.w ;гесі bottom 32 
ас.” ; rect right 32 
We read in the icons and store them in our iconmap, then call 
PlotIcon to display them in our dialog box. 

Getting access to the icons of an application requires that we 
open its resource fork. Given a filename, _OpenResFile returns 
the file reference number of the selected file. In order to simplify 
things, I used the standard file reply dialog to get 
‘rname+appreply’ or a filename from the dialog reply record. 
_OpenResFile also returns -1 to the stack if an error occurred in 
opening the resource file, such as ‘no resource file’ ,etc. Normally 
you would call _ResError to check for the specific error code if 
anything went wrong, but since we are only dealing with appli- 
cations, I skipped that step. Unless the file has been corrupted, 
every application will have a resource fork with at least one 
resource of type ‘CODE’. In the event of corruption, however, 
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k 


File Name: MacDraw 1.9 


rGood 
rType 
rUolume 
rUers ion 
rane 


; ignore command if FALSE 
; file type 

› volume reference number 
; file's version number 

; file nane 


IconApp will simply beep and return. One important thing to 
remember is that OpenResFile assumes that the resource file to 
be opened resides on the default volume, so we have to get the 
volume reference number from the sfreply record before opening 
any resource first. 
SearchIcon 

clr -CSP) ; room for resource file ref num 

lea rnametapprep ly, Al ; get filename 

поуе.1 A1,-CSP) 


-OpenResF i le open resource file 


7 
move (SP),D7 > D7=refnum 
cmpi 8- 1,D7 ; еггог?(по resources) 
bne Val idName ; no,get filename 
bre NoRez ; yes,beep and return 


Once we know the application has a resource fork, its time to 
look for any icons. Given a resource type, ‘ICN#’ in this case, 
_CountResources will return the total number of resources in the 
chosen file. Applications with unique icons always have at least 
one “ІСМЯ” resource, but larger applications often have file or 
document icons as well. 


ValidName 
CheckDItem "3 ; get statictext handle 
томе. Т  theItemCA5),-CSP) 
реа rname+apprep ly ; get our filename 
-SetIText ; print it in dialog 
clr -(SP) ; room for * of icons 
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move.L — "'^ICN'"^,-CSP) ; resource type 


-CountResources 

move (SP),D5 ; get * of icons in file 

Subq #2,D5 

cmpi #1,D5 ; is there at least one icon? 
blt NoIcon ; по, say 50 

bra DoIcon ; otherwise,prepare to plot it 


At the beginning of IconApp, the handle of a generic icon 
bitmap was stored in A4. If an application doesn't have an ‘ICN#’ 
resource, both the filename and the generic icon will be plotted 
in our dialog box. 

Since the total number of icons in the selected application 
was stored in D5, creating a loop to plot each icon is straight 
forward. D6 will be an index to the next plotted icon. Any 
application which has reached this point will contain at least one 
‘ICN#’ resource, so D6 is initialized to 1. GetIndResource can 
be used to call a number of resources consecutively, so passing 
рб and a resource type to _GetIndResource returns a handle to 
the resource. Each time an icon is plotted, the index to the last 
iconis compared to the total number of resources in the file. I only 
included frames for three icons, so if the last plotted icon is not 
the third one, D6 is incremented and we return to plot the next 


File Name: Draw 1.9 


Fig.2: MacDraw Icon 


File Name: Window 


Elg.3;: Generic Icon 

one. The reference number of the most recently opened resource 
file was saved in D7 when the file was first opened, so we pass 
that same refnum to  CloseResFile before dealing dealing with 
another application. 

In order to draw both a generic icon and any icon resources 
in an application, I used BlockMove (register-based), where AO 
points toa source, A1 points toa destination and DOis the number 


of bytes to transfer from one rectangle to another. In this case, AO - 


is a handle to the icon and A1 points to a 128-byte bitmap which 
will hold the icon. Since we want the entire icon, DO contains 128. 
In order to transfer the icon bit map to the screen, we call 
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_Ploticon which will draw the icon in a pre-specified rectangle in 


the dialog box. 
MACRO IconDrew IRect = 

clr.1 -(SP) 
nove.L 8 ^ICON* ^, -CSP) 
move D6, -CSP) 
-GetIndResource 
move. 1 СР ),Аб 
movea. 1 CAD), AB 
стра. | 80 А0 
beq CloseRez 
lea iconmap,A1 
movea. | CA1),A1 
move. 1] # 128,00 
-BlockMove 
pea (IRect) 
lea iconmap,A1 
move.1 А1,-(ӨР) 
-PlotIcon 


_BlockMove is a useful way to transfer bitmap images to the 
screen. It is also a neat way to achieve flicker-free animation 
without resorting to the dreaded alternate screen buffer. 

User Notes 

IconApp is a very simple application, but it demonstrates 
how to use bitmaps and manipulate resource files effectively. 
Using the program is easy: just click on the ‘Icons’ button and 
select a file in the normal way. Both the application and docu- 
ment icons of the selected file, along with the application name, 
will be printed out in the dialog box. IconApp will search for and 
draw up to three icons in the frames. 

Some corrupted applications which have been bundled and 
have a unique icon will appear on the Desktop with a generic 
icon. IconApp will plot the correct icon in the icon frames instead 
of the one that appears in the Finder. This is because it reads the 
icon from the application file and not the desktop file, so even if 
two applications have the same file creator tag, our utility will 
display the proper icon. 


; IconApp 
Include МасТгәрѕ.0 


Include SysEqu.D 
Include PackMacs. Txt 


;—_— Macros 
; IconDraw assumes that D5 contains the total number 

; Of resources of type ‘ICN®’ in the application, and 

; D6 is an index to the icon we are going to plot next. 
; M-? the sourcerect,A1-? the destrect and 

; 00-› the number of bytes to transfer. 


MACRO IconDraw IRect = 


с1г.1 -($Р) ;hendle 

move.L 871058” -(5Р) гез type 

move D6, - (SP) ; index 

- Get IndResource 

тоуе.1 СР), Аб 

тоуеа.1 САЙ), Аб ;hendle to ptr 
стра.1 80 А0 nil? 


beq CloseRez jyes, so exit 
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lea iconmep,A1 
movea.] (AD,A1 


CloseIt 


move.1 СА2),-С5Р) ; get dialog ptr. 


поуе.1 8128,00 -CloseDialog ; close dialog 
-BlockMove ;copy icon res to iconmap -ExitToShe11 ; exit... 
pea (IRect) GetF ile 


lea iconmap,A1 


get icon handle 


move.1 A1,-CSP) 


move.w 8 100,-(sp) ; upper corner of reply box 
move.w *102,-Csp) 


-PlotIcon ;plot icon in rect pea scratch ; dummy string 
| с1г.1 -(sp) ; filter 
move #],-(5р) ; only epplications 
MACRO CheckDItem Items реа apptype ; type list 
move.1 (А2),-(ӨР) ; get Dialog pointer сіг.1 -(5р) ; dialog hook 


move.w (Item) ,-CSP) 


; Dialog item in question 


pea theType(CA5) ; VAR type 
pea thel temCA5) ; VAR item 
pea theRect(A5) ; VAR box 


pea appreply ; reply record 

move #2,-Csp) ; standard file reply dialog 
-pack3 

move rgoodtappreply,d@ ; was a file chosen? 


-GetDI tem beq DialogLoop ; no, return 
lea parmblock(A52,A0 ; Ай-» parameter block 
XDEF START ; linker requisite сіг.1 ioCompletionCAd) ; no conpletion routine 
; — — ——tquetes lea appreply,Al ; A1 reply record 
AllEventsequ $0000FFFF move.w 6CA 1), ioVRefNumCAQ) ; get drive refnum 
DWindLen equ $AA clr.1 ioVNPtrCA0) ; volume name pointer 
j Initialize Managers -SetVol 
START SearchIcon 
pea -4(A5) push Quickdraw globals clr -(SP) ; room for resource file ref num 


_InitGraf init Quickdraw 


; 
; lea rnametappreply,Al ; get filename 
-InitFonts ; init Font manager 


move.1 A1,-CSP) 


-InitWindows ; init Window manager -OpenResF i le ; open resource file 
-InitMenus init Menu manager move (SP),D7 > D7=refnum 
clr.1 -(SP) ; no restart procedure cmpi 8-1,07 ; error?(no resources) 
-InitDialogs ; init Dialog manager Bne ValidName ; no,get filename 
-TEInit ; init TextEdit bra NoRez ; yes,beep and return 
move.] #AllEvents,D@ ; all standard events NoRez 
-FlushEvents ; flushed from event queue move 20, -(SP) 
-InitCursor ; get standard arrow cursor -SysBeep 

j—— — — ———Miscelleneous bra DialoglLoop 
move.1 8128 00 ; 128 bytes for icon ValidName 


-NewPtr ; get pointer CheckDItem #3 ; get statictext handle 
стрі 80 DO ; еггог? move.] theItemCA5), -CSP) 

Bne Quit ; yes, exit out pea rnametappreply ; get our filename 
lea iconmap,A1 ; го, get handle to icon -SetIText ; print it in dialog 


move.] AQ,CA1) ; save pointer to icon data cir -(SP) 
поме. *^ICON^,-CSP) ; res type for icon 
move ®128,-(SP) ; ResID of our generic icon 


; room for 8 of icons 
move.L ®’ICN®’ -CSP) ; resource type 
-CountResources 


-GetResource ; get generic icon from system move (SP),D5 ; get " of icons in file 
move.1 (ӨР),А4 ; save its handle in A4 Subq 82,05 
bra IconInfo ; get IconDialog box cmpi 81,05 ; is there at least one icon? 
Quit blt Nolcon  ; no, say so 
-ExitToShe11 bra Dolcon  ; otherwise,prepare to plot it 
Qo —————Ó—À—M———S DoIcon 
IconInfo move #],06 ; get first icon 
сіг.1 -(SP) ; get room for Dialog pointer IconDrew ісопгесі1; plot it 
move.w & 160, -С5Р) ; resource ID | cmp D5,D6 ; is this the only icon? 
реа IconDialog(A5) ; Storage for Dialog record beq CloseRez ; yes,close resource file 
поуе.1 8-1,-(ӨР) ; in front of other windows addq 81,06 ; no,add one to counter 
-GetNewDialog bra DolIcon2 ; get second icon 
lea IconHendle,A2 ; duplicate handle DoIcon2 
поуе.1 CSP),CA2) ; leave handle on stack IconDrew iconrect2; plot second icon 
-DrewDialog ; drew dialog box and.. cmp 05,06 ; is there а third icon? 
lea IconHandle, А2 beq CloseRez ; no, close resource file 
поуе.1 СА2),-С5Р) ; set port to us айда 81,06 ; yes, add опе to counter 
-SetPort bra DoIcon3 ; get third icon 
DialogLoop DoIcon3 


bsr Outline ; outline the 'quit^ button IconDrew iconrect3; plot third icon 


bsr GetFremes ; drew our three icon frames bra CloseRez ; close resource file 

сіг.1 -($Р) ; no filter proc NoIcon 

pea ItemHit ; VAR ItemHit CheckDItem #3 ; get statictext handle 
-ModalDialog move.] theItemCA5), -CSP) 


move ItemHit,DO ; Get Item chosen реа гпате+арргер1у ; get our filename 

cmp.b %1,00 ; Quit? -SetIText ; print it in dialog 

beq.s CloseIt move. А4,А0 ; get handle of generic icon 
cmp.b "2,00 ; get appl. icon? movea.1 (А0),А0 ; A®-> sourcerect 

beq.s GetFile стра.1 #9, Ad 

bra DialogLoop =; no,wait for a valid choice beq CloseRez 
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lea iconmap,A1 


movea. | 


move. 1 8128 00 


; A1 destrect 
СА12,А1 
; 00 - number of bytes to move 


-BlockMove 

pea iconrect] 
lea iconmap,A1 
move. 1 A1,-CSP) 


-PlotIcon 
bra DialogLoop 


GetFrames: 


; plot generic icon 
; return 
; print icon frames 


pea iconframe! 
-FrameRect 
pea iconframe2 
-FrameRect 
pea iconframe3 
-FrameRect 


rts 


OutLine: ; outline first item in dialog, or 'quit^ button 
CheckDItem #] 
move t3, -CSP) 
move #3, -CSP) 


-PenS ize 


pea theRect(A5) 
move 8-4, 


; VAR box 


-($Р) 


move #-4,-($Р) 
-InsetRect 

pea theRect(A5) 
move 4 16, -CSP) 
move 8 16, -CSP) 
-FrameRoundRect 


rts 
CloseRez 


move D7, -CSP) 
-CloseResF i le 
bre DialogLoop 


; UT*rsrc.file refnum 
; close resource file 
; return 


;————— Local storage————— 


Even tRecord 


What: 


dc.w8 j;what event number 


Message: dc.19 ;ptr. to msg 
When: dc.10 ;Time event was posted 
Point: dc.18 ;тоџѕе coordinates 
Modify: dc.w8 ;state of keys & button 
Window:  dc.18  ;Find window’s result 
IconHendle dc.19 
ItemHit dc.w8 ; dialog items 
scratch 
dc.b 14 
dc.b '' 
dc.1£ 
epptype dc.b ‘APPL’ 
dcb.b 14, 8ff 
apprep ly dc.w5 
dc.b 63 
dcb.b 63,0 
iconmap dc.w 0,0,4,0,0,$20,$20 
iconrect 1 dc.w 17,61,49,93 
iconrect2 dc.w 17, 128,49, 152 
iconrect3 dc.w 17, 174,49, 206 
iconfremel dc.w 10,57,54, 98 
iconframe2 dc.w 10, 115,54, 156 
iconfreme3 dc.w 10, 169,54,210 
1—0 1068 1 S 
IconDialog ds.w DWindLen 
theType ds.w 1 ; VAR for GetDItem 
theItem ds.11 ; VAR for GetDI tem 
theRect ds.w 4 ; VAR for GetDI tem 
parmb lock ds.w 80 
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; IconApp_rscs.ASM 


RESOURCE ‘INAP’ 0 ‘IDENTIFICATION’ 


DC.B 15, ‘ICON RETRIEVER ‘ 


. ALIGN 2 
RESOURCE ‘BNDL’ 128 'BUNDLE' 


DC.L — 'INAP" )МАМЕ OF SIGNATURE 
DC.W 0,1 ;DATA CDOESN’T CHANGE) 
DC.L ‘ICNR’ ; ICON MAPPINGS 
DC .W 0 ;NUMBER ОҒ MAPPINGS-1 
DC.W 0,128 ;МАР 0 TO ICON 128 
DC.L ‘FREF’ ;FREF MAPPINGS 
DC.W 0 ;NUMBER OF MAPPINGS-1 
DC .W 0,128 ;МАР 0 TO FREF 128 


RESOURCE ‘FREF’ 128 'FREF 1’ 
DC.B ‘APPL’, Ø, Ø, Ø 


. ALIGN 2 
RESOURCE ‘ICN®’ 128 ‘MY ICON’ 


; APPLICATION ICON BIT MAP 


DC.L $00000000,$00000000,$3FFFFFFC,$35555554 
DC.L $2AAAAAAC, $35555554, $2AAAAAAC, $35FFFFDA 
DC.L $2B0000AC, $354000D4, $284000AC , $35580004 
DC.L $285000AC,$35500004, $2B 1380АС, $35 148004 
DC.L %280280АС, $3502A0D4, %280382АС $35002AD4 
DC.L $280026АС, $350022D4, $280000AC $35000004 
DC.L $2BFFFFAC, 435555554, $2ААААААС, $35555554 
DC. L $2ААААААС, $3FFFFFFC, 600000000 $00000000 


x. L %00000000,%00000000, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC, $3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC, $3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC, $3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC,$3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC, $3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC, $3FFFFFFC, $3FFFFFFC, $3FFFFFFC 
DC.L $3FFFFFFC,$3FFFFFFC, 500000000. $00000000 


. ALIGN 2 
RESOURCE ‘ICON’ 128 ‘THE ICON’ 


; GENERIC APPLICATION ICON BIT МАР 


DC.L $00010000,$00028000,$00044000 , $00082000 
DC.L $00101000,$00200800,$00400400 , $00800200 
DC.L $Ø 1000 100 02000080) %04000040,%08000020 
DC.L $10000010 ' $20000008, $40003F04 , %80004082 
DC.L $4000804 1, $200 13022, $ 190 1C8 14 , $080ЕТЕВЕ 
DC.L %04023007,%020 10007, $01008007 , $00806007 
DC.L $0040 1FE7,$002002 IF, $00 100497, ,$00080800 
x. L $0004 1000, $00022000, $000 14000, $00008000 


OC. L $00010000,$00038000, $0007C00, $0000ҒЕ000 
DC.L $00 1ЕҒ000,8003ҒҒ800, $207FFCO, $000FFFEDD 
DC.L $0 1FFFFOO, $03FFFF80, $7FFFFC, $00FFFFFEO 
DC.L $iFFFFFFO,$3FFFFFF8, $7FFFFFF, $CFFFFFFFE 
DC.L $7FFFFFFF, $3FFFFFFE, $ 1FFFFFF, $COFFFFFFF 
DC.L $O7FFFFFF, $03FFFFFF, $01FFFFF, $FOOFFFFFF 
DC.L $O07FFFFF, $O03FFE IF, $00 IFFCO, $7000F F800 
DC.L $0007F000, $0003E000, $000 100, $000008000 


„ALIGN 2 
RESOURCE ‘DLOG’ 160 ‘Icon Dialog’ 
DC.W 107, 122,227,376 ;BoundsRect 
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. ALIGN 2 


RESOURCE ‘DITL’ 168 ‘Icon..’ 


— Q HT 2 ow 
~ 
е „„ 


‘Icon...’ 


STRING_FORMAT 2 


DC.W 


DC.L 
DC.W 
DC.B 
DC.B 


DC.L 
DC.W 
DC.B 
DC.B 


DC.L 
DC.W 
DC.B 


3 


ø 
86, 194, 115,248 
4 


Quit’ 


й 
86, 106, 115, 185 
4 


“Ісопв..” 


0 
60,78,76,241 
8 


М 
д 
9 
; 
д 
2 


; Dialog box w/ outline 
; Visible 
; NoGoAway 


Ref Con 


* DITL ResID 
‚ Title 


33 Items (4-123) 


we We We We 


wee We We We 


handle holder 
BoundsRect 
Button 81 
title 


handle holder 
BoundsRect 
button 82 
title 


; handle holder 
; BoundsRect 
statictext #1 


me 


DCB “/ 

DCL 8 ; handle holder 
DC.W 60,3, 76,76 ; BoundsRect 
DC.B 8 ; Statictext 82 


DC.B ‘File Name: ’ 
STRING-FORMAT 0 ; normal 


ISTART 

[ 

) 

/OUTPUT IconApp 
IconApp 


/TYPE ‘APPL’ ‘INAP’ 
/BUNDLE 

/RESOURCES 
IconApp_rscs 


50 


© The Essential MacTutor, Vol. 3 


Assembly Lab 
A Midi Library for Pascal 


What Is MIDI? 

Before I get too much into the nuts and bolts of this whole 
thing perhaps we should take a look at what it’s all about. MIDI 
is an acronym for Musical Instrument Digital Interface, and 
really came into being somewhere around 1983. Originally, it 
was created to allow music synthesizers to communicate with 
each other, but there was enough foresight in the minds of the 
originators to leave room for future enhancements. As far as the 
scope of this article is concerned, the most important thing about 
MIDI is that it allows music synthesizers to communicate with 
computers, specifically, the Macintosh. 

The need for a standard 

To really understand why MIDI came about, you have to 
know a little bit about the history of music synthesizers. In the 
late 1960’s synthesizers were, for the most part, voltage con- 
trolled devices. That is, you could control the frequency of an 
oscillator (a tone generating device) by varying a DC voltage that 
was routed to one of its control inputs. The higher the voltage, the 
higher the note and vice versa. The standard that was used by 
companies like Moog and ARP was 1 volt/octave. This meant 
that if your control voltage changed from 4 volts to 5 volts the 
oscillator would shift its pitch higher by one octave. 

This “voltage control” concept worked pretty well at the time, 
but you have to remember that the hardware itself was pretty 
primitive by today’s standards. For instance, most synthesizers 
in that era could only play one note at a time. Chords could only 
be created by using a multitrack tape recorder and overdubbing 
the different notes. This was how recordings like “Switched On 
Bach” were produced. 

Now, when you’re only dealing with a note at a time things 
aren't too complicated. Still, you had to make sure all of your 
oscillators were in tune, because typically you would have to use 
more than one oscillator to produce a respectable sounding note. 
Then all of the oscillators would have to be scaled so that they 
would track accurately. These last two points were no small 
problem, because the analog oscillators at that time had a very 
large problem — thermal drift. This meant that you could tune 
and scale all of the oscillators very carefully, and 5 minutes later 
they would be out of calibration because the temperature of the 
semiconductor junctions had changed. Ahh, those were fun days. 

But, those problems aside, there were other signals that were 
needed to produce a note besides just a control voltage for the 
oscillator. You also needed a trigger pulse to tell the synthesizer 
when to start playing a note. Then you needed a way to let the 
synthesizer know that you wanted to stop a note when you lifted 
your finger from the keyboard. This was usually in the form of 
a “gate” signal. Okay, so now we’re up to three signals just to 
produce one note ata time. Then, as if that weren’t enough, some 
manufacturers were using a positive going pulse as the trigger 
and others were using a negative going pulse. You could get 
around this problem with special adaptor boxes and the like, but 
then a much larger problem came looming over the horizon -- 
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polyphony. 

Polyphony means the ability to play more than one note at a 
time, and even though it was a tremendous breakthrough for the 
musician, it multiplied the problems for electronic musical 
instrument designers. Now, to the best of my knowledge, the 
polyphonic synthesizer keyboard that we know and love today 
came into being around 1978 thanks to the advent of the micro- 
processor and the talents of a couple of guys named Dave Rossum 
and Scott Wedge of Emu Systems. Their ideas led to the use of 
microprocessor based keyboards by virtually all of the synthe- 
sizer manufacturers. Oberheim was one of the first companies to 
bring out a polyphonic instrument. It had a keyboard that was 
scanned by the microprocessor which then converted the infor- 
mation into DC control voltages and gate signals for controlling 
its analog oscillators, filters, and amplifiers. The amazing thing 
about this instrument was that it actually worked, and it provided 
a great leap forward for synthesizers in general. But, now another 
problem began to appear. 

Musicians wanted to have a remote keyboard controller that 
could be worn around their neck and send signals down a cable 
to their synthesizers which might be offstage somewhere. Or 
maybe they didn’t want a keyboard at all! Maybe they wanted to 
control a synthesizer from a guitar or a drum set! Instrument 
designers were really starting to get overwhelmed by all of the 
options that musicians were demanding at this point, and it 
became clear that there was a need for some kind of standard way 
for controllers (keyboards, guitars, drums) and synthesizers (the 
sound producing electronics) to communicate with each other so 
that instruments made by different manufacturers could work 
together. 

MIDI is born 

Inlate 1981 a paper was presented to the Audio Engineering 
Society suggesting a digital, serial interface for electronic music 
synthesizers. This scheme was referred to as the Universal 
Synthesizer Interface, and was authored by Dave Smith and Chet 
Wood of Sequential Circuits. This proposal was, in fact, the 
precursor to MIDI, and served as the impetus to get manufactur- 
ers of electronic musical equipment to talk with each other about 
some sortof communications standard. What finally came out of 
all of the discussions was the MIDI specification 1.0. 

The data not the sound 

Now, probably the most confusing thing about MIDI to the 
beginner is understanding that MIDI is concerned with control 
data, and not the actual sound itself. For instance, if we talk about 
a MIDI recorder that emulates many of the functions of a 
traditional tape recorder you must understand that the MIDI 
information that is being recorded is simply the note on and note 
off signals. When a key is pressed on a synthesizer keyboard 3 
bytes of MIDI information are sent over the serial connection 
telling the sound producing electronics to start playing a note (the 
details of these 3 bytes will be explained shortly). When that 
same key is finally released another 3 bytes of information is sent 
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over the MIDI cable telling the sound producing electronics to 
stop playing that note. As you can readily conclude from this 
simple example, a note of any length requires the same amount 
of information — 6 bytes. This is what makes for such compact 
use of memory in MIDI recorders. By comparison, actually 
recording the sound itself by an analog to digital conversion 
would take tens of thousands of bytes even fora very short sound, 
and a longer sound would require more memory still. But, even 
more importantly, the use of MIDI control signals allows musi- 
cians to factor out the actual sound from the note choices and 
timing information. This means that I can play a part on a piano- 
style keyboard, record iton a MIDI recorder, and then play itback 
with the ability to change the actual soundas itis playing. So now 
what I recorded as a piano sound can be played back as a trumpet 
sound, or a violin sound, or a marimba sound. This is what gives 
tremendous power to MIDI recorders. А musician can enter in 
all of the notes without prior knowledge of what the final 
arrangement is going to be, then change instruments on the fly to 
help with the decision making process that is necessary to create 
a final arrangement. In this regard, the MIDI recorder is to the 
traditional tape recorder as the Word Processor is to the type- 
writer. It is a powerful tool that goes far beyond emulating its 
traditional counterpart. 
The command set 

Here are a few of the morecommon MIDI commands that are 
used to control synthesizers. For a copy of the full specification 
(which is much longer than this article allows), write to: 

International MIDI User's Group 

8426 Vine Valley Dr. 

Sun Valley, CA 91352 

Note on 

This is the data that is sent when a key goes down on a 

synthesizer keyboard. 


5100 1nnnn 
Where nnnn is the MIDI Channel Number (0-15) 
BOkkkkkkk 
Where kkkkkkk is the Key Number (0-127) 60 = middle C 
SÜvvvvvvv 
Where vvvvvvv is the velocity 
Note off 
This is the data that is sent when a key is released on a 
synthesizer keyboard. 
$1000nnnn 
Where nnnn is the MIDI Channel Number (0-15) 
BOkkkkkkk 
Where kkkkkkk is the Key Number (0-127) 60 = middle C 
SÜvvvvvvv 
Where vvvvvvv is the velocity 
All notes off 
This is a useful command that is typically sent when a 
sequence is terminated before the end of the file. This command 
turns off all of the notes that are playing to avoid the disastrous 
problem of *stuck notes" (what happens when a note on com- 
mand is not followed by a corresponding note off command). 


% 18 11nnnn 
Where nnnn is the MIDI Channel Number (0-15) 
891111011 
200000000 
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Aftertouch 

This is the data that is sent when pressure is applied to the 
synthesizer keyboard while the key is being held down. 

$119 1nnnn 

Where nnnn is the MIDI Channel Number (0-15) 

 АЙуууууУУ 

Where vvvvvvv is the amount of aftertouch 

Program change 

This command changes the current sound that the synthesizer 
is playing. 

%1188nnnn 

Where nnnn is the MIDI Channel Number (0-15) 

Üppppppp 
Where ppppppp is the Program Change Number (0-127) 
Pitch Wheel 

This is the data that is sent when the pitch bend wheel on a 
synthesizer is moved from its center position. 

8$1110nnnn 

Where nnnn is the MIDI Channel Number (0-15) 

Süvvvvvvv 


Where vvvvvvv is the LSB of the Pitch Wheel Change 


 ҰЙуууУУУУ 
Where vvvvvvv is the MSB of the Pitch Wheel Change 
Continuous controllers 
These are generalized controllers that could correspond to 


knobs on a particular synthesizer. Continuous controller #1 is the 
Modulation Wheel by default. 


% 181 1nnnn 
Where nnnn is the MIDI Channel Number (0-15) 
%0ссссссс 
Where ссссссс is the control number (0-121) 
Süvvvvvvv 
Where vvvvvvv is the control value 
The serial ports 
The Macintosh serial ports were not really constructed with 
MIDI in mind, unfortunately, but you can make them work by 
using a few special techniques that we'll talk about now. 
Hardware 
Theoutputs of the Mac serial ports have to be level shifted and 
translated to a standard TTL gate output in order to meet the MIDI 
spec. The inputs have to be optoisolated. If you wanta quick and 
dirty schematic of the necessary hardware check MacTutor's 
October 1985 issue, or The Best of MacTutor, volume 1. 
Software 
The timing of MIDI information is one of the more difficult 
demands that the Macintosh has to deal with. I mean, it doesn't 
really matter if your spreadsheet calculates a formula in 2 
seconds or 2.02 seconds, but that much difference in a musical 
performance is totally unacceptable. In order for the information 
to be processed as quickly as possible we have to use interrupts 
to handle tasks like transmitting and receiving bytes of MIDI 
data, and updating the timing reference. 
Time-Stamping 
Now, just sending and receiving bytes of MIDI information 
is just fine for a lot of applications, but typically you want to not 
only get the incoming data, but also know when it arrived. This 
is necessary for applications like recorders where you log the 
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time that the data came in so you can play it back with the correct 
timing. Sounds simple huh? Well, itis and itisn't. Forone thing, 
in order to accurately record the time you have to use a technique 
called “іте-ѕіатріпр”, and you have to do it on an interrupt 
level. That is, when the interrupt routine is called because the 
SCC chip has a byte that has just arrived at the Mac, the routine 
not only has to get that byte from the SCC chip and place it in a 
buffer area, but it also has to get a counter value (that has been set 
up previously) and tag it onto the incoming MIDI byte. Then 
when it's time to play the data back the counter is started up and 
you sit there and watch the counter for each byte of information 
to be sent out at the appropriate time (this is a really crude 
example involving no data compression). 

Okay, not to difficult, but it gets more complicated. To set up 
acounter that you can use to reference all of this stuff to you have 
to use one of the timers in the 6522 chip. There are two timers, 
appropriately called timer1 and timer2. Unfortunately, timer] is 
the most accurate timer to use if you want to create continuous 
interrupts at a specified time interval (the interval we will be 
using will be in the millisecond range). This is because timer1 
automatically reloads itself after it times out. Timer2 requires 
that your interrupt routine reload it after it times out, and you 
never know how long it is going to take before your interrupt 
routine can respond to a timer2 interrupt. Now, if your timing 
doesn't have to be that accurate you can go ahead and use timer2, 
in fact, this is the way that the Time Manager routines in Inside 
Macintosh vol. 4 appear to work. So, you can simply use the 
Time Manager routines if you find that to be easier, and aren't 
that concerned with absolute timing accuracy. 

The reason that you might want to use timer? it that timer1 is 
used by the Sound Manager routines, so if you are using timer1 
for time-stamping incoming MIDI data you can't use any of the 
Sound Managerroutines, you haveto write to the sound hardware 
directly in order to produce a click track or whatever. Anyway, 
that’s the tradeoff. I have written the following code using timer1 
since you can simply ignore it if you want to use the Time 
Manager routines and everything will be fine. If you want to use 
timer] call InitTimer at the beginning of your application, and 
QuitTimer at the end of it. Conversely, if you don’t want to use 
it don’t call either of those routines (or any of the other timer/ 
counter routines). 

Overview 

Okay, here’s how you go about using these routines for MIDI 
software. Now, let me say in advance that I know you’re not 
supposed to write data to your own code segments, but I did it this 
way because alot of people complained about the use of (A5) 
variables in the November 1985 MacTutor article. In a future 
article I'll present another way to do MIDI that doesn't use the 
approach I'm using here, but for now, this should get you going 
since the problems won't appear until the Macintosh II starts 
using the memory management chip. 

Initialization 

When your application starts up it should call InitSCCA and/ 
or InitSCCB depending on whether you are going to use one ог 
both channels (A is the modem port, B is the printer port). If you 
are going to use the counter then you should also call InitTimer 
when your application starts up. 

Receiving data 

To receive a MIDI byte call RXMIDIA or RxMIDIB depend- 

ing on which port you are using. When you call these routines 
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you must leave space on the stack for a longword result. The 
MIDI byte is in the lower 8 bits of the longword, and the upper 
3 bytes contain the value of the counter when the byte arrived at 
the SCC chip. 
Transmitting data 

To send a byte of MIDI data use the routines TxMIDIA or 
TxMIDIB depending on which port you want to use. To use these 
routines simply place a word on the stack with the MIDI byte in 
the lower 8 bits and call the appropriate routine. 

The Counter 

To set the counter to a value of 1 call StartTimer. The value 
of 1 is used instead of 0 because the 0 value is used as a special 
flag. You should know that the counter value defaults to 1 when 
your application starts up. 

To get the current value of the counter call GetCounter. This 
routine requires that you leave space on the stack for a longword 


result. The longword contains the counter value. 


UNIT LSPMIDI; 


INTERFACE 
PROCEDURE InitSCCA; 
(call this once at the beginning of your application if) 
(you are going to use the modem port for MIDI) 


PROCEDURE TxMIDIA CTheData : integer); 

(use this procedure to transmit a byte of MIDI data ) 
(through the modem port the MIDI byte is in the ) 
(lower 8 bits of the word) 


FUNCTION RxMIDIA : LongInt; | 

(use this function to get a byte of MIDI data and) 

(the counter value Sedo in tad) 

(with that byte through the modem port) 

(the MIDI byte is in the lower 8 bits of the longword) 
(the upper 3 bytes of the longword contain the counter ) 
(value when the byte arrived at the Macintosh) 


PROCEDURE ResetSCCA; 

(са11 this procedure when your application is done if) 
(you called InitSCCA at the beginning of your ) 
{application or the system will crash) 


PROCEDURE InitSCCB; 
(call this once at the beginning of your application} 
(if you are going to use the printer port for MIDI) 


PROCEDURE TxMIDIB (TheData : integer); 

(use this procedure to transmit a byte of MIDI data) 
(through the printer port the MIDI byte is in the lower ) 
(8 bits of the word) 


FUNCTION RxMIDIB : LongInt; 

(use this function to get & byte of MIDI deta and) 

(the counter value 855516164) 

(with that byte through the printer port) 

(the MIDI byte is in the lower 8 bits of the longword) 
(the upper 3 bytes of the longword contain the counter) 
(value when the byte arrived at the Macintosh) 


PROCEDURE ResetSCCB; 

(call this procedure when your application is done ) 
(if you called InitSCCB at the beginning of your) 
(epplication or the system will crash) 


PROCEDURE InitTimer (TimrValue : integer); 
(call this procedure once at the beginning of your) 
(epplication if you ere going to) 


(neke use of time-stamping. 1 millisecond = decimal 782) 
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PROCEDURE LoadTimer (TimrValue : integer); ; 6522 equates 


(call this procedure if you want to change the) VIA EQU $ 104 
(interval of time that the counter) vT1C EQU $800 
(is incremented. 1 millisecond = decimal 782) vT 1CH EQU %А00 
“Т X EQU$ C00 
PROCEDURE StartCounter; vACR | EQUÉ 1600 
(call this procedure to set the counter value to 1) vIER Е00$1С00 
FUNCTION GetCounter : LongInt; ; XDEF 811 routines that need to be accessed externally. 
(call this function to get the current value) 
(of the counter) XDEF InitSCCA 
XDEF InitSCCB 
PROCEDURE QuitTimer; XDEF TxMIDIA 
(call this procedure when your application is done) XDEF TxMIDIB 
(if you called InitTimer at) XDEF RxMIDIA 
(the beginning of your epplication or the system ) XDEF RxMIDIB 
(will crash) XDEF ResetSCCA 
XDEF Rese tSCCB 
IMPLEMENTATION XDEF InitTimer 
($A+ XDEF LoadTimer 
PROCEDURE InitSCCA; XDEF Star tCounter 
external; XDEF GetCounter 
PROCEDURE TxMIDIA; XDEF QuitTimer 
external; 
FUNCTION RxMIDIA; ; These аге the routines for the Modem Port 
external; 
PROCEDURE ResetSCCA; 
external; ; PROCEDURE InitSCCA; 


PROCEDURE InitSCCB; ; Call this routine at the beginning of your application if 


external; ; using the modem port for MIDI information trensfers. 
PROCEDURE TxMIDIB; InitSCCA 
external; MOVE SR,-CSP) ; Seve interrupts 
FUNCTION RxMIDIB; MOVEM.L D0/A0-A2, -CSP) ; Seve registers 
external; ORI "$0300, SR ; Disable interrupts 
PROCEDURE ResetSCCB; 
external; MOVE.L — SCCRd,A1 ; Get base Reed eddress 
PROCEDURE InitTimer; ADD "aCt1,A1 ; Add offset for control 
external; MOVE .B (А12,00 ; Dummy read 
PROCEDURE LoadT imer; MOVE.L (SP), (SP) ; Delay 
external; MOVE .L SCCWr, Ad ; Get base Write address 
PROCEDURE StartCounter; ADD taCt1, Ad ; Add offset for control 
external; MOVE .B 80 (A0) ; pointer for SCC reg 9 
FUNCTION GetCounter ; MOVE.L  C(SP),(SP) ; Delay 
external ; MOVE .B 8%10000000,(А0) ; Reset channel 
PROCEDURE QuitTimer; MOVE.L Р), CSP) ; Delay 
" EORR BSR InitSCCChan ; brench to common init routine 
A- 
; set up the interrupt vectors 
ды MOVE.L — "LvI2DT, Ad 
| | | s. | i у ,M ; get dispetch table ptr 
; repo кыре e а stamping MOVE HRxIntOffsetA,DB ; get offset to Rx vector 
; Written by Kirk Austin 5/17/87 — | LEA — PRxIntHendA,A1 ; point to previous vector stor 
; This code is in the public domain end is absolutely free MOVE.L САВ 00) CAD) eave ; ; 
; l ) 00), Р previous int vector 
2 Note: Be sure end turn off renge checking in LS Pascal LEA RxIntHandA, А1 : set Rx vector 
; to prevent а crash. MOVE.L А1,0СА0 00) ` 
‚ Serial Chi t MOVE "STxIntOffsetA,DO ; get offset to Tx vector 
nd M Eau $ 108 ES LEA — PTxIntHendA,A1 ; point to previous vector stor 
SCCN EQU $ 10C MOVE.L OCA, DØ), CA1) ; save previous int vector 
Г LEA — TxIntHendA, A1 ; set Tx vector 
aDate : 2 MOVE.L А1,0САб,00) 
act] ЕФ MOVE tiSpecRecCondA,DO ; offset to Special vector 
bet EQU ~ LEA — StubA,A1 
TBE EQU2 MOVE.L — A1,0CA0,00) 


QU 


Lv11DT E . | 
LvI2DT EQU $ 182 LEA — RxByteInA, A2 ; get the address 

IntOffsetA — EQU24 CR (А2) 
о LEA — RxByteOutA, A2 ; get the address 
TxIntOffsetA EQU 16 
SpecRecCondA EQU28 CLR CA2) 

А RxQEmptyA,A . h 

RxIntOffsetB EQU8 LE xQEmptyA, А2 ; get the address 


MOVE — "$FFFF,CA2D 


TxIntOffsetB — EQUO LEA — TxByteInA, A2 ; get the address 


SpecRecCondB EQU 12 


54 © The Essential MacTutor, Vol. 3 


CR | (O2 MOVE SR,-CSP) ; Save interrupts 
LEA  TxByteOutA, А2 ; get the address MOVEM.L 00 /А0-АЗ,-(ӨР) ; Seve registers 
CLR (А2) ORI "$0300 , SR ; Disable interrupts 
LEA TxQEmptyA, А2 ; get the address 
MOVE — "$FFFF, CA2) LEA TxQEmp tyA, АЗ ; get the address 
TST.B (A3) ; is TxQueue empty? 
MOVEM.L CSP +, DB/AB-A2 ; Restore registers BNE TxQEA ; if so branch 
MOVE (SP )+,SR ; Restore interrupts LEA TxByte Ind, АЗ ; get the address 
RTS ; and return MOVE (A3)2,D0 ; if not add byte to queue 
LEA TxQueueA, А2 ; point to queue 
; This is the common initialzation routine for both channels MOVE.B 9(462,0CA2,D0)  ; place byte in queue 
ADDQ 81/00 ; Update TxByteIn 
Ini tSCCChan CMP "$ 100,00 
MOVE.B 84 (Ай) ‚ pointer for SCC reg 4 BNE e1 
MOVE.L (SP), CSP) ; Delay MOVE “0,00 
MOVE.B 8%10000100,(А0) ; 32x clock, 1 stop bit @1 MOVE 00 (АЗ) 
MOVE.L (SP), (ӨР) ; Delay BRA TxExitA ; end exit 
MOVE.B 81 (Ай) ; pointer for SCC reg 1 
MOVE.L (ӨР), CSP) ; Delay TxQEA 
MOVE.B н500000000, Ад) ; No W/Req MOVE.L SCCRd, Ай ; get SCC Read Address 
MOVE.L (SP), CSP) ; Delay MOVE .L SCCWr,A1 ; get SCC Write address 
MOVE.B 83 (AQ) ; pointer for SCC reg З MOVE аС+1,00 ; get index for Ctl 
MOVE.L (SP), CSP) ; Delay BIST .B 8TBE,0CA0,D0) ; transmit buffer empty? 
MOVE.B 8400000000,(А0) ; Turn off Rx BNE FirstByteA ; if so branch 
MOVE.L (SP), (SP) ; Delay LEA TxByteInA, A3 ; get the address 
MOVE.B 85 (AQ) ; pointer for SCC reg 5 MOVE (A32,D0 ; if not add to queue 
MOVE.L (SP), CSP) ; Delay LEA TxQueueA, А2 ; point to queue 
MOVE.B "200000000, (А0) ; Turn off Tx MOVE.B 9(462,0CA2,D0)  ; place byte in queue 
MOVE.L (SP), CSP) ; Delay ADDQ 81,00 ; update pointer 
MOVE.B $11,CA0) ; pointer for SCC reg 11 CMP 1$ 100,00 
MOVE.L (SP), CSP) ; Dela BNE 61 
MOVE.B "2001901000,C(A0) ; Make TRxC clock source MOVE #000 
MOVE.L (SP), CSP) ; Delay @1 MOVE 00,(АЗ) 
MOVE.B 114 (A0) ; pointer for SCC reg 14 LEA TxQEmp tyA, АЗ ; get the address 
MOVE.L (SP), CSP) ; Delay MOVE 80,CA3) ; reset queue empty flag 
MOVE.B "200000000,C(A0) ; Disable BRGen BRA TxExitA ; end exit 
MOVE.L (SP), CSP) ; Delay 
MOVE .B 83, CAD) ; pointer for SCC reg 3 FirstByteA 
MOVE.L (SP), CSP) ; Delay MOVE #aData,DØ ; get index to data 
MOVE .B "511000001, CA0) ; Enable Rx MOVE .L CSP), CSP) ; delay 
MOVE.L (SP), CSP) ; Delay MOVE .B 9(46),0CA1,D0) ; write data to SCC 
MOVE .B 85 (AQ) ; pointer for SCC reg 5 MOVE.L ФР), (SP) ; Delay 
MOVE.L (SP), (ӨР) ; Delay 
MOVE .B 8401101010,(А0) ; Enable Tx and drivers 
MOVE.L (SP), CSP) ; Delay TxEx itA 
MOVE.B 815, CAB) ; pointer for SCC reg 15 MOVEM.L (5Р2%,00/А0-АЗ ; Restore registers 
MOVE.L (ӘР), (ӨР) ; Delay МОУЕ (SP)+,SR ; Restore interrupts 
MOVE .B 150000 1000, CAG) ; Enable DCD int for mouse UNLK A6 ; release frame pointer 
MOVE.L (ӨР), (ӨР) ; Delay MOVE.L (SP)*,A1 , save return address 
MOVE.B 80 (А0) ; pointer for SCC reg 0 ADD.L 82 SP ; Move past data word 
MOVE.L (SP), CSP) ; Delay MOVE .L A1,-CSP) ; put address back on stack 
MOVE .B 15000 10000 (Ай) ; Reset EXT/STATUS RTS ; end return 
MOVE.L CSP), CSP) ; Delay 
MOVE.B 80 CAD) ; pointer for SCC reg 0 , . FUNCTION RxMIDIA : LongInt; 
MOVE.L (SP), CSP) ; Delay ; This routine gets а byte through the modem port. 
MOVE.B 85000 10000,(А0) ; Reset EXT/STATUS again ; To use this routine treat it like а Pascal 
MOVE.L (SP), CSP) ; Delay ; function. Leave space on the stack for a longword 
MOVE.B 81, (AQ) ; pointer for SCC reg 1 ; Of data before calling this routine. If the data 
MOVE.L (SP), (ӨР) ; Delay ; on the stack after 
MOVE.B #3000 10011, CA0) ; Enable interrupts ; the routine executes is Ø there was no MIDI data available. 
MOVE.L (SP), СР) ; Delay ; If it’s non-8 the upper 3 bytes contain the counter 
MOVE .B 89 САЙ) ; pointer for SCC reg 9 ‚ value, the MIDI byte is the low byte. 
MOVE.L (ӨР), CSP) ; Delay RxMIDIA 
MOVE .B 8%00001010,(А0) ; Set master int enable LINK A6, #9 ; set frame pointer 
MOVE.L (SP), (SP) ; Delay MOVE SR,-CSP) ; Save interrupts 
RTS MOVEM.L D0-D1/A0-A3,-CSP) ; Save registers 
ORI "$0300, SR ; diseble interrupts 
; . PROCEDURE TxMIDIA CTheDeta : integer); 
; This is the routine to transmit a MIDI byte of data LEA RxQEmptuA , АЗ ; get the address 
; through the Modem Port.To use this routine place TST.B САЗ) ; any data available? 
; the byte to be transmitted as the lower 8 bits BEQ e1 ; if so, brench 
; Of а word on the stack, then call TxMIDIA. MOVE .L %0 ,8CA6) ; if not, return with 0 
TxMIDIA BRA RxEx itA 
LINK Аб, 0 ; set frame pointer 61 LEA RxByteOutA, АЗ ; get the address 
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MOVE CA3), DO ; get index to byte out 

LEA RxQueueA , А2 ; point to queue 

MOVE.L #0,D1 ; clear data register 

MOVE.L 0(A2,00),D1 ; get MIDI dete 

MOVE.L D1,8CA6) ; place on stack for 
return 

ADDQ 84/00 ; update index 

CMP 1$400,D0 

BNE e2 

MOVE 0,00 
@2 LEA RxByteOutA, АЗ ; get the address 

MOVE 00, САЗ) 

(ҒА RxByteInA, A3 ; get the address 

MOVE (АЗ),01 

СМР 00,01 ; is queue empty? 

BNE RxExi tA ; if not exit 

LEA RxQEmp tyA, A3 ; get the address 

MOVE "$FFFF ,CA3) ; if empty, set flag 
RxExi tA 

MOVEM.L (5Р)%,00-01/А0-АЗ ; Restore registers 

MOVE (SP)*,SR ; restore interrupts 

UNLK A6 

RTS ; and return 


299-9 Wwe ө Ve Be 


This is the interrupt routine for receiving through 
the modem port. It places the counter value and the 
MIDI byte in a circular queue to be 

accessed later by the application. 

When the system gets this far, Аб contains the 

SCC base read Ct! address 

and A1 contains the SCC base write Ct! address 

for this chennel.The data addresses are offset by 4 
from the control addresses. 

D0-D3/Ag-A3 ere already preserved, so they may 

be used freely. 


xIntHandA 

MOVE SR, -CSP) 
ORI "$0300, SR ; disable interrupts 

@3 MOVE 84/00 ; get data offset 
CLR.L D1 ; prepare for data 
MOVE.L (SP), CSP) ; Delay 
MOVE .B 0(А0,002,01 ; read data from SCC 
MOVE.L (SP), (SP) ; Delay 
LEA RxQueueA , А2 ; point to queue 
LEA RxByteInA, A3 ; get the address 
MOVE (АЗ2,00 ; get offset to next cell 
LEA Counter, АЗ ; get the address 
MOVE.L CA3),D2 ; put counter value in D2 
LSL.L #8 D2 ; shift counter one byte 
ADD.L 02,01 ; combine counter and data 
MOVE.L D1,0CA2,D0) ; put longword in queue 
LEA RxQEmptyA, АЗ ; get the address 
MOVE 80 (АЗ) ; reset queue empty flag 
ADDQ 84/04 ; update index 
CMP $400 , DØ 
BNE 61 
МОУЕ 80/00 

01 LEA RxByte InA, АЗ ; get the address 
MOVE DØ, (АЗ) 

02 ВТ5Т.В 80 (A0) ; is there more data? 
BNE e3 ; do it again if there is 
MOVE CSP )+, SR ; enable interrupts 
RTS ; and return 


we "e We We Be We 


This is the interrupt routine for transmitting a byte 
through the modem port.It checks to see if there 

is any data to send, and if there is it sends it to 
the SCC. If there isn’t it resets the TBE interrupt 
in the SCC and exits. 

When the system gets this far, AØ contains the SCC 
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: base read Ct] address and A1 contains the SCC base 
: write Ctl address for this channel. 


: addresses. 00-03/А0-АЗ are already preserved, so 


The data addresses are offset by 4 from the control 
д 


; they тау be used freely. 


TxIntHandA 
MOVE 
ORI 


LEA 
TST.B 
BEQ 
MOVE .B 
MOVE.L 
BRA 

@1 LEA 
MOVE 
LEA 
MOVE 
MOVE . B 
MOVE .L 
ADDQ 
CMP 
BNE 
MOVE 

@2 LEA 
MOVE 
LEA 
MOVE 
CMP 
BNE 
LEA 
MOVE 


TxIExitA 
MOVE 
RTS 


SR,-CSP) 

"$0300,SR ; disable interrupts 
TxQEmptyA, A3 ; get the address 

(A3) ; Is queue empty? 

ei ; if not brench 

"$28,(A1) ; if so, reset TBE interrupt 
(SP),CSP) ; Delay 

TxIExitA ; end exit 

TxByteOutA, АЗ ; get the address 
САЗ) ,00 ; get index to next data byte 
TxQueueA, А2 ; point to queue 

84/01 ; get data offset 
0(А2,00),0(А1,01) ; write data to SCC 
(SP), (SP) ; Delay 

81,00 ; update index 

"$ 100,00 

@2 

в0 00 

TxByteOutA, АЗ ; get the address 
DO, CA3) 

TxByteInA, A3 ; get the address 
(АЗ),01 

00,01 ; is TxQueue empty? 
TxIExitA ; if not exit 
TxQEmp tyA, A3 ; get the address 
"$FFFF , САЗ) ; if empty set flag 
CSP)+,SR ; enable interrupts 


PROCEDURE ResetSCCA; 
› If you called InitSCCA at the beginning of your 
; application this routine must be called when 
; the application quits or the system will 
: crash due to the interrupt handling pointers 


esetSCCA 
MOVEM.L 
MOVE 
ORI 


MOVE.L 
ADD 

MOVE.B 
MOVE.L 
MOVE.B 
MOVE.L 


: becoming invalid. 
R 


00/А0-А1,-(ӨР) 


and return 


м ө 


; save registers 


SR,-CSP) ; Save interrupts 
"$0300, SR ; Diseble interrupts 
SCCWr , Ad ; Get base Write address 
*aCt1,A0 ; Add offset for control 
80 (А0) ; pointer for SCC reg 9 
(SP), СР) Delay 

8%10000000 (А0) ; Reset channel 

CSP), (SP) ; Delay 


BSR Rese tSCCChan 


routine 


MOVE.L 
MOVE 


MOVE .L 
MOVE 


MOVE .L 
MOVE 
MOVEM .L 
RTS 


SLv12DT, Ad 


; branch to common reset 


; dispatch table pointer 


SRxIntOffsetA,DO ; get offset to Rx vector 
LEA PRxIntHandA,Al ; point to previous vector stor 


(A1), ØCAO DB) 


; restore previous int vector 


"TxIntOffsetA,DO ; get offset to Tx vector 
LEA — PTxIntHandA, A1 


(A12,0CA0, DB) 


(SP)+,SR 


($Р)+ ‚00 /Ай-А1 


; Set Rx vector 

; restore previous int vector 
; Restore interrupts 

; restore registers 

; end return 


; This is the common reset routine for both channels 


ResetSCCChan 


MOVE.B 
MOVE.L 


8 15, CAB) 
CSP), CSP) 


; pointer for SCC reg 15 
; Delay 
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MOVE.B 840000 1000, CAG) ; Enable DCD int 


7 
MOVE.L (SP), CSP) ; Delay 
MOVE .B 80 (AQ) ; pointer for SCC reg 0 
MOVE.L (SP), CSP) ; Delay 
MOVE .B 8200010000,CA0) ; Reset EXT/STATUS 
MOVE.L (SP), CSP) ; Delay 
MOVE.B 80 CAB) ; pointer for SCC reg 0 
MOVE.L (SP), (ӨР) ; Delay 

b 


MOVE.B #800010000, (AD) 
; DeMgyE.L (Р), (SP) 
MOVE.B 81, (AB) 


Reset EXT/STATUS again 


pointer for SCC reg 1 


MOVE.L (SP), (ӨР) ; Delay 

MOVE .B 8%00000001,СА0) ; Enable mouse interrupts 

MOVE.L (SP), CSP) ; Delay 

MOVE.B "9 (AQ) ; pointer for SCC reg 9 

MOVE.L (SP), CSP) ; Delay 

MOVE .B "5000010 10, (А0) ; Set master int enable 

MOVE.L (SP), CSP) ; Delay 

RTS 
TxQueueA DCB.B  $100,0  ; this is the queue 
TxQEmptyA DC 0 ; the queue empty flag 
TxByteInA DC 0 ; index to next cell in 
TxByteOutA DC 0 ; index to next cell out 
RxQueueA DCB.B  $400,0  ; this is the queue 


RxQEmp tyA DC 0 ; the queue empty flag 
RxByteInA DC 0 ; index to next cell in 
RxByteOutA DC 0 ; index to next cell out 
PRxIntHandA ІСІ Ø  ; Previous interrupt vector 
PTxIntHandA . DC.L 0  ; Previous interrupt vector 


; Тһезе аге the routines for the Printer Port 
; PROCEDURE InitSCCB; 

; Call this routine at the beginning of your 
, application if you are going 

; to be using the printer port for MIDI 

; information trensfers. 


InitSCCB 
MOVE SR, -CSP) ; Save interrupts 
MOVEM.L 00/А0-А2,-(5Р) ; Save registers 
ORI "$0300,SR ; Disable interrupts 
MOVE.L SCCRd, Al ; Get base Read address 
ADD *bCt1,Al ; Add offset for control 


MOVE.B CA1), DØ ; Dummy read 

MOVE.L (SP), (SP)  ; Delay 

MOVE.L SCCWr , Ad ; Get base Write address 
ADD "bCtl,A0 ; Add offset for contro] 
MOVE.B "9 (AQ) ; pointer for SCC reg 9 

MOVE.L (SP), (SP) ; Delay 

MOVE.B 3201000000,CA0) ; Reset channel 

MOVE.L (SP),CSP) ; Delay 

BSR InitSCCChan ; branch to common init routine 


; Set up the interrupt vectors 


MOVE.L 8 У120Т,А0 ; get dispatch table pointer 


MOVE BRxIntOffsetB,DO ; get offset to Rx vector 

LEA — PRxIntHandB,A1 ; point to previous vector stor 
MOVE.L ØCAG, DO), CA 1) ‚ save previous int vector 
LEA RxIntHandB, A! ; Set Rx vector 

MOVE.L А1,0СА0,002 

МОУЕ 8TxIntOffsetB,00 ; get offset to Tx vector 

LEA PTxIntHandB,A1 ; Set Rx vector 

MOVE.L ØCAG, DØ), CA1) ; Save previous int vector 
LEA TxIntHandB, A! ; set Tx vector 

MOVE.L A1,0CA0,D0) 

MOVE "SpecRecCondB, DØ ; offset to Special vector 


LEA — StubB,A1 
MOVE.L А1,0СА0,00) 


; initialize the flags & pointers 


LEA — RxByteInB, А2 ‚ get the address 
CR (42 
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LEA — RxByteOutB, A2 ; get the address 


CR (А2) 

LEA RxQEmptyB,A2 ; get the address 
MOVE — "FFFF, (A2) . 

(ҒА TxByteInB,A2 ; get the address 
CR | (O2 

LEA — TxByteOutB, A2 ; get the address 

CR (А2) 

LEA — TxQEmptyB, А2 ; get the address 


MOVE — "$FFFF,CA2) 


MOVEM.L — (SPO*,D0/A0-A2  ; Restore registers 
MOVE . CSPO*,SR ; Restore interrupts 
RTS ; end return 


, . PROCEDURE TxMIDIB (TheData : integer); 

; This is the routine to transmit а MIDI byte of 

; dete through the Printer Port. 

; To use this routine place the byte to be transmitted 
; as the lower 8 bits 

; Of а word on the stack, then call TxMIDIB. 


TxMIDIB 
LINK 
MOVE 
MOVEM.L 
ORI 
LEA 
TST.B 
BNE 


@1 MOVE 


BRA 
FirstByteB 
MOVE 
MOVE.L 
MOVE.B 
MOVE .L 
TxExi tB 
MOVEM.L 
MOVE 
UNLK 
MOVE.L 
ADD.L 
MOVE.L 
RTS 


A6, #8 ; set frame pointer 
SR,-CSP) ; Save interrupts 
00 /А0-АЗ,-(5Р) ; Save registers 


"$0300, SR ; Disable interrupts 
TxQEmp tyB , АЗ ; get the address 

(A3) ; is TxQueue empty? 
TxQEB ; if so branch 
TxByteInB, A3 ; get the address 
(АЗ2,00 ; if not ада byte to queue 
TxQueueB, A2 ; point to queue 
9(А62,0(А2,00)  ; place byte in queue 
81,00 ; update TxByteIn 
8%100,00 

01 

10,06 

DØ, САЗ) 

TxExitB ; end exit 

SCCRd, Ad get SCC Read Address 


SCCWr, A1 ; get SCC Write address 
"bCt1,D0 ; get index for Ctl 
8ТВЕ,0(А0,00) ; transmit buffer empty? 
FirstByteB ; if so branch 

TxByteInB,A3 ; get the address 

САЗ),00 ; if not add to queue 
TxQueueB,A2 ; point to queue 
9(46),0CA2,00) ; place byte in queue 


81,00 ; update pointer 
“$ 100,00 
1 

80 00 
DØ, САЗ) 
TxQEmp tyB, АЗ ; get the address 
80 САЗ) , reset queue empty flag 
TxExitB ; end exit 
8bDate,D6 ; get index to data 
(SP), (SP) ; delay 
9(462,0(41,00) ; write data to SCC 
(SP), CSP) ; Delay 

(SP2*,D0/A0-A3 ; Restore registers 
(SP)+,SR ; Restore interrupts 
A6 ; release frame pointer 
(SP)*,A1 , Seve return address 
82 SP , Move past data word 
А1,-(ӨР) ; put address back on stack 


; end return 


) FUNCTION RxMIDIB : LongInt; 

; This routine gets а byte through the printer port. 

) To use this routine treat it like a Pascal function. 
; Leave space on the stack for a longword 
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of data before calling this routine. If the 
data on the stack after 

the routine executes is 0 there was no MIDI 
data available. If it’s non-@ 

the upper 3 bytes contain the counter value, 


the MIDI byte is the low byte. 


xMIDIB 
LINK А6,%0 ; Set frame pointer 
MOVE SR, -CSP) ; Seve interrupts 
MOVEM.L 00-01/А0-АЗ,-(ӨР) ; Save registers 
ORI 1$0300 SR ; diseble interrupts 
LEA RxQEmptyB, A3; get the address 
TST.B (A3) ; any data avai lable? 
BEQ e1 ; if so, branch 
MOVE.L %0 8(Аб) ; if not, return with 0 
BRA RxExi tB 
e1 LEA RxByteOutB, АЗ ; get the address 
MOVE CA3), DØ ; get index to byte out 
LEA RxQueueB,A2 ; point to queue 
MOVE.L 80, D1 ; clear data register 
MOVE.L ØCA2,DØ),D1 ; get MIDI data 
MOVE.L D1,8CA6) ; place it on stack for return 
ADDQ 84,00 ; updete index 
CMP "$400 ,00 
BNE e2 
MOVE #0,00 
@2 LEA RxByteOutB, АЗ ; get the address 
MOVE 00, САЗ) 
(ҒА RxByteInB,A3; get the address 
MOVE (АЗ),01 
СМР 00,01 ; is queue empty? 
BNE RxExitB ; if not exit 
LEA RxQEmptyB, A3; get the address 
MOVE "SFFFF,CA3) ; if empty, set flag 
RxExitB 
MOVEM.L (SP?*,D0-D1/A0-A3 ; Restore registers 
MOVE (SP )+,SR ; restore interrupts 
UNLK A6 
RTS ; and return 


P e EP PP PE E Be Be He He He He He Se 


This is the interrupt routine for receiving through 
the printer port. 

It places the counter value and the MIDI byte in а 
circular queue to be 

accessed later by the application. 

When the system gets this fer, Аб contains the 

SCC base reed Ct! address 

and А1 contains the SCC base write Ct! address 

for this channel. 

The data addresses ere offset by 4 from the 
control eddresses. 

D0-D3/A0-A3 аге already preserved, so they 

may be used freely. 


xIntHendB 
MOVE SR, -CSP) 
ORI "$0300,SR ; disable interrupts 

e3 MOVE 84/00 ; get data offset 
CLR.L 01 ; prepare for dete 
MOVE.L (SP),CSP) ; Delay 
MOVE .B @С(А0,00),01 ; read data from SCC 
MOVE.L (SP), (SP) ; Delay 
LEA — RxQueueB,A2 ; point to queue 
LEA — RxByteInB, A3 ; get the address 
MOVE (АЗ),0@ ; get offset to next cell 
LEA — Counter, АЗ ; get the address 
MOVE.L САЗ ),02 ; put counter value іп 02 
LSL.L 88,02 ; Shift counter one byte 
ADD.L 02,01 ; combine counter апа dete 
MOVE.L 01,0(А2,00) ; put longword in queue 
LEA — RxQEnptyB, АЗ ; get the address 
MOVE 80 (АЗ) ; reset queue empty flag 
ADDQ 14 D6 ; updete index 
СМР %%400,00 
BNE 61 
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МОУЕ 80/00 
61 LEA RxByteInB,A3; get the address 
MOVE 00,(АЗ) 
e2 BIST.B %0 (А0) ; is there more dete? 
BNE e3 ; do it again if there is 
MOVE (SP)+,SR ; enable interrupts 
RTS ; end return 


; This is the interrupt routine for trensmitting 
; & byte through the printer port. 

: [t checks to see if there is апу deta to send, 
; end if there is it sends it to 


; the SCC. 


If there isn’t it resets the TBE 


; interrupt in the SCC and exits. 
; When the system gets this far, Аб contains 
‚ the SCC base read Ct] address 


: for this channel. 

: The date addresses are offset by 4 from the 

; control addresses. 

: 00-03/Ай-АЗ are already preserved, so they may 
; be used freely. 


4 
9 
9 
д 
д 
д 
* end Al contains the SCC base write Ct! address 
д 
д 
д 
T 


xIntHendB 
MOVE SR, -CSP) 
ORI "$0300,SR ; disable interrupts 
LEA TxQEmptyB, A3 ; get the address 
TST.B (A3) ; Is queue empty? 
BEQ ei ; if not brench 
MOVE.B — 1428,(AD ; if so, reset TBE interrupt 
MOVE.L (SP),CSP) ; Delay 
BRA Tx IExi tB ; end exit 

@1 LEA TxByteOutB, A3 ; get the address 
MOVE CA32,D0 ; get index to next data byte 
LEA TxQueueB, A2 ; point to queue 
MOVE 84/01 ; get data offset 
MOVE . B 0CA2,D02,0CA 1,01) ; write data to SCC 
MOVE.L (SP), CSP) ; Delay 
ADDQ 81,00 ; Update index 
CMP "$ 100,00 
BNE e2 
MOVE «0,00 

62 LEA TxByteOutB, A3 ; get the address 
MOVE DØ, CA3) 
LEA TxByteInB,A3 ; get the address 
MOVE (АЗ),01 
CMP 00,01 ; is TxQueue empty? 
BNE TxIExitB ; if not exit 
LEA TxQEnptyB, A3 ; get the address 
MOVE S$FFFF,CA3) ; if empty set flag 

TxIExitB 
MOVE CSP)+,SR ; enable interrupts 
RTS ; end return 


Zehn 


PROCEDURE ResetSCCB; 
If you called InitSCCB at the beginning of your 
application this 
routine must be called when the application 
quits or the system will 
cresh due to the interrupt handling pointers 
becoming invalid. 


esetSCCB 
MOVEM.L D9/A9-A1,-CSP) ; save registers 
MOVE SR,-(SP) ; Seve interrupts 
ORI X !$0300,SR ; Diseble interrupts 
MOVE.L SCCwr, Ad ; Get base Write address 
ADD *bCt1,Ad ; Add offset for control 
MOVE .B 89 CAB) ; pointer for SCC reg 9 
MOVE .L (SP), (SP) ; Delay 
MOVE.B %%01000000,(А0) ; Reset channel 
MOVE.L (SP) (SP) ; Delay 
BSR — ResetSCCChen ; branch to common reset routine 
MOVE.L #Lv12DT,Að ; get dispatch table pointer 
MOVE SRxIntOffsetB,D8 ; get offset to Rx vector 
LEA PRxIntHandB,Al ; point to previous vector stor 
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MOVE.L (A12,0CA0,D0) ; restore previous int vector 
MOVE 8STxIntOffsetB,DO ; get offset to Tx vector 

LEA PTxIntHandB,A1 ; Set Rx vector 

MOVE.L СА 12,0(А0,00) ; restore previous int vector 


MOVE CSP )+,SR ; Restore interrupts 
MOVEM.L (SP)*,D0/A9-A1 ; restore registers 
RTS ; and return 
TxQueueB DCB.B  $100,0  ; this is the queue 
TxQEmp tyB DC 8 ; the queue empty flag 
TxByteInB DC 0 ; index to next cell in 
TxByteOutB DC д ; index to next cell out 
RxQueueB DCB.B  $400,0 ; this is the queue 


RxQEmp tyB DC 
RxByte InB 0С 0 
RxByteOutB DC 
PRxIntHendB 0041 
PTxIntHandB — DC.L 


; the queue empty flag 

; index to next cell in 

; index to next cell out 

; Previous interrupt vector 
; Previous interrupt vector 


CU 


This is the space for а special condition interrupt 
routine. A11 I do here is reset the error flag in the SCC 
and return. When the system gets this far, AQ contains 
the SCC base read Ctl address 

and A1 contains the SCC base write Ct! address 

for this channel. 

The data addresses are offset by 4 from the control 
addresses. 00-03/А0-АЗ are already preserved, so 

they may be used freely. 


[do We Ve Ve We Ge 


tubA 
ORI 1$0300 , SR ; Diseble interrupts 
MOVE.B $8200110000,CA1) ; Reset Error 
MOVE.L <Р), (SP) ; Delay 
ANDI "$F8FF ,SR ; Restore interrupts 
RTS 


; This is the space for a special condition interrupt 
; routine.All I do here is reset the error flag in 
; the SCC апа return. When the system gets this fer, 
; Аб contains the SCC base read Ctl address 
; and А1 contains the SCC base write Ctl address 
; for this channel. 
; The data addresses are offset by 4 from the 
; control addresses. 
; 00-03 /Ад-АЗ are already preserved, so they may be 
; used freely. 
StubB 
ORI 1!$0300 , SR 
MOVE.B 152091100900, (A1) 
MOVE.L (SP), CSP) 
ANDI "$F8FF SR 
RTS 


Disable interrupts 
Reset Error 

Delay 

Restore interrupts 


we We We We 


These are the routines for the counter you can use for 
time-stamping the incoming MIDI data. This is useful 
for writing sequencer type applications. 
The time-stamping is done on an interrupt level, 
is extremely accurate, 
and uses the VIA timer #1. This means that you can’t 
use any of the Sound Manager routines because they use 
timer 81 too. If you went to create a metronome click 
you have to write your own code that accesses 
the sound hardware directly without using timer #1. 
InitTimer and LoadTimer expect a word on the stack 
to load the timer. 
To increment the counter every millisecond, load the 
timer with decimal 782. If you aren’t going to use 
time-stamping you can ignore these routines. 
PROCEDURE InitTimer (TimrValue : integer); 
Only call InitTimer once at the beginning 
of your application 1 millisecond is decimal 782. 
nitTimer 
LINK A6 , #8 ; set frame pointer 
MOVEM.L 00/А0-А1,-(ӨР) 
MOVE.L #Lv11DT,A® ; Point to level 1 dispatch table 
LEA — PrevIVC,A1 ; point to interrupt vector storage 


к“. ъъ. м. ъъ. -- м. -.-. We We We He He Ve Ge Ve Be De 
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MOVE.L 24CA0), CA1) ; save previous interrupt vector 
LEA Counter IntHand, A1 
MOVE.L A1,24CA0) ; put it in the dispatch table 
MOVE .L VIA,Al ; point to the 6522 chip 

ORI.B 8%40 УАСВСА1) 
MOVE .B 1$С0 ,УТЕВСА1) ; Enable timer interrupts 
MOVE 8СА62,00 ; Get timer value 

MOVE.B DO,vTILCA1) ; set timer 10 byte 


LSR "8,00 ; Shift to hi byte 

MOVE.B 00 vT1CHCA12 ; set timer hi byte 

MOVEM.L (5Р2%,00/А0-А1 

UNLK A6 

MOVE.L CSP)+, Ай ; save return address 
ADDQ #2, SP ; move past timer value 
MOVE.L A0,-CSP) ; replace return address 
RTS 


; . PROCEDURE LoadTimer (TimrValue : integer); 
; Call LoadTimer whenever you want to change the timer value. 
; 1 millisecond is decimal 782. 


LoadT imer 
LINK A6, #9 ; set frame pointer 
MOVEM.L 0б /AB-A1,-CSP) 


MOVE.L  VIA,A1 ; point to the 6522 chip 
MOVE 8(A6),D0 ; Get timer value 
MOVE.B — DO,vTILCA DD ; set timer 10 byte 


LSR 18,00 ; Shift to hi byte 

MOVE.B DO,vT1CHCA12 ; set timer hi byte 

MOVEM.L (SP?*,D0/A9-A1 

UNLK A6 

MOVE.L CSP)+, A ; save return address 
ADDQ 82 SP ; move past timer value 
MOVE.L A8, -CSP) ; replace return address 
RTS 


; .. PROCEDURE StartCounter ; 
; StertCounter sets the counter value to 1 
StartCounter 
LEA Counter, Аб 
MOVE .L 81 (Ай) 
RTS 
; FUNCTION GetCounter : LongInt; 
; GetCounter returns а longword that is the value 
; of the counter 
GetCounter 
MOVE.L — A8,-CSP) 
LEA Counter, Аб ; point to the counter 
MOVE .L (A0),8CSP) ; return it as function result 
MOVE.L (SP)+, Ad 
RTS 
PROCEDURE QuitTimer; 
: Call QuitTimer when your application is done or the system 
will crash. 
QuitTimer 
MOVEM.L A0-A1,-CSP) 
MOVE.L VIA, A1 ; Diseble 6522 interrupts 
MOVE.B "$40, vIERCA1) 
LEA — PrevIVC,A1 ; Restore previous interrupt vector 
MOVE .L УТ idt, Аб 
MOVE.L (A12,24CA0) 
MOVEM.L (5Р)%,Ай-А1 
ЕТ5 
; This is the interrupt handler routine for the counter. 
; When the system gets this far А1 contains the base 
; address of the VIA. 
; It also preserves 00-03/А0-АЗ. 


; point to the counter 
; set it to 1 


Counter IntHand 

LEA — Counter, AQ ; point to the counter 

ADDQ.L #1, CAB) ; Increment it 

MOVE.B vT1CCA12,D0 ; Clear interrupt flag on 6522 

RTS - 
Counter DC.L 1  ; The counter 1 
PrevIVC 001 0 ; Previous interrupt vector Ced 

END EDS, 
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;point to new interrupt handler 


; Set the timer to freerun mode 


Assembly Language Lab 


Formatted Output for Numbers 


On most systems, programmers of high level languages have 
an advantage over assembly language programmers in that a lot 
of the nitty gritty detail work has been done for them by what ever 
compiler or interpretter they’re using. An example of this is in the 
outputting of numbers. High level language programmers usu- 
ally take it for granted that they can output a number in just about 
any format they want to. Pascal’s writeln and C’s printf make it 
a trivial task to change the field width of both integers and reals. 
While it’s true that assembly programmers can make use of 
. NumToString or the SANE formatter, we still need to play with 
the resulting strings to get nice formatted numbers. Until now. 


CONVERTING INTEGERS 


The basic idea when converting an integer into its string 
equivalent is to first break it down into its digits and then convert 
each digit into its ASCII equivalent. The only tricky part is that 
a number is represented as binary internally and we need its 
decimal equivalent. 

There are at least 2 different ways to approach the problem of 
extracting base 10 digits from a binary number. The 
_NumTOoString routine that Apple provides in the system file (see 
listing 1) uses binary coded decimal (BCD) arithmetic to calcu- 
late the digits and then calls a separate subroutine to build the 
string two digits at a time (the least significant bytes of registers 
D1-D5 are used to store 2 BCD digits each). The main problem 
with this algorithm is that it runs in more or less constant time (the 
number 1 takes as long to convert as 2147483648 = 2431) and 
isn’t very efficient except for very large numbers (about 7 or 
more digits). 

Another way to get digits one by one is to subtract by 
successively smaller powers of 10, starting with 1049 (since it is 
the largest power of 10 that can be represented by a 32 bit integer). 
Count how many times you can subtract each power of 10 from 
the number and then convert that number (which will be in the 
range 0..9) to its ASCII equivalent. If you use multi-word 
compares and subtracts, this method can be used to convert any 
size integers (like 64 or 128 bits) into strings. 

My own NumToString routine (Shown in the program list- 
ing) uses the subtract method. How does the subtract method 
compare to the real. NumToString? As for size, NumToString 
is 118 bytes (after all of the trap related instructions are removed) 
and my routine is 120 bytes. Pretty close. As for speed, time trials 
on 10,000 random 32 bit signed integers showed my routine to be 
faster by about 2% — no big deal. But for time trials on 10,000 
16 bit signed integers my routine was faster by 32% and for 
10,000 8 bit signed integers my routine was faster by 45% (to be 


60 


Mike™ Scanlin 
San Diego, CA 
MacTutor Vol. 3 No. 11 


Format Demo 


-20,353 + -32,270 
25,267 + 652 
17,005 
8,656 


= -52,623 

25,919 

32,949 

15,086 

8,291 
52.00031 
15.00007 


15,944 - 
6,430 
-997 
19,375 
8,320 
919,519 19,954 
950,227 3,572 (= 
05,956 / -28,261 = т 


9,288 + 
1,011,245 / 
125,809 / 

/ 
/ 


: 
Roa 
IH 08988985998 


Fig. 1 Demo Program formats numerical output 


+ -32,270 = -52,623 
* 652 = 25,919 
15,944 = 32,949 
6,430 = 15,086 
-997 = 8,291 
19,375 52.00031 
8,320 15.00007 
19,954 26.00004 
3,572 266. 00000 
-3.00006 


125,809 
519,519 
950,227 

85,956 / -28,261 


Fig. 2 Program supports easy updating with a 
picture 


fair, NumTosString was timed after it had been isolated so there 
was no overhead for trap calling). The reason the smaller num- 
bers showed so much improvement is because my routine 
doesn't spend much time on little digits (0,1,2...) and virtually no 
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time on leading zeros. If you have a time critical application that 
makes a lot of calls to NumToString, it may be worthwhile to 
use my routine instead. Of course, you could just patch my 
routine over the existing NumToString in the system file to 
speed up all applications that use _NumToString — no, wait, I 
didn't justsay that (and I' m not responsible for the consequences. 
Is there any reason that wouldn't work?). 


CONVERTING FIXED POINT REALS 


When you use DIVS or DIVU, the 32 bit result is made up of 
16 bits of quotient and 16 bits of remainder. The FixPtToString 
routine uses these two pieces to convert a fixed point number to 
a string. Since the quotient is just an integer, we can use 
NumToString to convert it. Then adda decimal point and convert 
the remainder. But in order to convert the remainder into a 
fractional number, we need to know the original divisor. We also 
need to specify how many digits we want after the decimal point. 

For each digit you want after the decimal point, the routine 
multiplies the remainder by 10 and then divides the it by the 
divisor, getting a new remainder in the process. It adds the digit 
to the string and then repeats the process for the next digit. 
However, there is a limited number of times that this can be done 
accurately (since we only have 16 bits of remainder to begin 
with). The number of digits that can be accurately calculated 
depends on the magnitude of the divisor, but 5 or 6 digits should 
be safe. 

Note that the number you pass to FixPtToString doesn’t have 
to be the result of a divide instruction. You can output any 
arbitrary fixed point number you want by using the same basic 
idea. If you wanted an integer part bigger than 16 bits, you could 
output the number in a two part process. FixPtToString could be 
modified to be FractionToString by eliminating instructions 3 
(EXT.L DO) thru 17 (BEQ.S @6) inclusive. Then it will tack on 
whatever fraction you pass it to what ever string you pass it. For 
instance, to output the number 1864723 135.24226 (.24226 = 47/ 
194): 


MOVE.L stringPtrCA5), Ad 


MOVE.L 81864723135,00 ;quotient 
JSR NumToStr ing 


MOVE 847,00 ,remainder 

SWAP 00 jno need to set quot 
MOVE 9 194,01 ;divisor 

MOVE 85,02 5 digits accuracy 


JSR  FractionToString 
MOVE.L AØ,-(SP) 
-DrewString 


FORMATTING 


Now that we can get integers and reals into strings we need to 
be able to set field widths. Also, an option to add commas would 
be nice. The FormNumString routine does both of these. You 
pass it a pointer to a format string of the form: [*,'][qU ." (21) 
where [ | denotes something optional and *.' and ‘, denote а 
constant character. Q and r are string variables in the range 
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['0"..99'] and represent how many spaces should be allocated for 
the quotient (including sign and commas) and remainder (not 
including decimal point). Notice that everything is optional, so 
the empty string is a legal one, but one that won't do much (i.e. 
any) formatting. Also, the word "string" here does not mean a 
pascal string; i.e. there is no length byte. The nested brackets 
mean that you can't have a *.' if aq was not provided and you 
can’t have anr if a *.' wasn't provided. If q is too small to contain 
the number, space is used as needed. If it is too big, the number 
will be padded with spaces. If r is bigger than any existing 
remainder the number might have, zeros are appended after the 
decimal point (which doesn't do much for the accuracy of the 
extra digits). If r is smaller than any existing remainder, then 
digits are just dropped. No attempt at rounding is made. 

Another use for this routine is to reformat the output string 
from the SANE formatter. The SANE formatter can format any 
SANE data type into a fixed sytle number (see the Apple Numer- 
ics Manual for everything you ever wanted to know about 
SANE). So, you could use SANE to do all of your calculations in 
floating point and have your result formatted into a fixed style 
string and then use FormNumString to add commas, pad with 
spaces and delete decimal places (or add zeros) to make all your 
numbers uniform. 


PUTTING IT ALL TOGETHER 


The 3 routines NumToString, FixPtToString and FormNum- - 
String have been pieced together to form DrawNumsInAString 
which can be used to output complete sentences containing any 
number of formatted numbers. For instance, you could pass it the 
string “result = V,8.4." along with the fixed point number 
123456.789 and it will output “result = 12,3456.7890." Each 
number you want formatted in the input string will begin with a 
4” character and be followed by an 4” (for longints) or an ‘f’ (for 
fixed points). After that comes the FormNumString style format 
codes for the number. The only peculiar part of using the routine 
is that the numbers you want formatted have to be pushed on the 
stack in reverse of their occuring order in the string. For instance, 
if your input string looks like “x = N4 y 2N4 2 = N4" then you 
would do this: 


MOVE.L z,-CSP) ;3rd parameter 


MOVE.L y,-CSP) ; 2nd 
MOVE.L x,-CSP) 164 
РЕА inputString 

JSR DrewNumsInAStr ing 


The reason for passing the parameters that way is (1) because 
we don't know how many will be present in advance, and (2) so 
that they can be taken off the stack in the order needed. 

DEMO PROGRAM 
The FormatDemo program shows how all of this comes 


together. Itis a bare bones application that demonstrates how the 
routines presented here might be used. A click in the window will 
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generate another set of random numbers to format. Desk acces- 
sories are supported and you can see a simple technique for 
providing window updating without an update event. Whenever 
acontent click is detected, a set of addition and division problems 
are displayed in formatted output using the formatting routines 
discussed. After displaying the numbers, a quickdraw picture is 
taken of the window output using copybits on the portRect of the 
window. The appropriate field in the window record is set with 
the pointer to this picture so that when the window needs 
updating, it is updated automatically from the picture. Figures 1 
and 2 show the demo program in operation with a desk accessory 
showing this easy update method. A good reference book for this 
and all assembly language techniques is Dan Weston's classic 
The Complete Book of Macintosh Assembly Language 
Programming, vol. 1 and2, from Scott, Foresman and Company. 


Listing 1. The Apple Way 


; NOTE: This code is Apple Computers. Only 
; the comments are mine. 


NuaToString 


9 

; convert а 32 bit longint into а pascal string 
; input: 00 longint 

f AO points to a space of at least 12 bytes 
; Output: Аб points to pascal string 


MOVEM.L D2-D6/A1,-CSP) 
MOVEQ 80,01 ,init digits 


MOVEQ 80,02 
MOVEQ %0,03 
MOVEQ — *0,04 
MOVEQ 80,05 
MOVEQ #31,D6 ; loop counter 
LEA 1(А02,А1 ;Skip length byte 
TST.L 00 jis num zero? 
BGT.S 62 
BMI.S 61 
MOVE.B %’9',CA1)+ ;әресіа1 case for zero 
BRA.S 63 
@1 MOVE.B 8’-’,(CA1)+ ;give string a minus sign 
NEG.L DØ ;m&ke number positive 
02 ADD.L 00,00 ;Shift a bit into extend flag 
ABCD 05,05 ;tens^ & ones’ digits 
ABCD 04,04 ; thous’ & hunds’ digits 
ABCD 03,03 ;hund thous’ & ten thous’ digits 
ABCD 02,02 Жеп mils’ & mils’ digits 
ABCD 01,01 ;bils^ & hund mils’ digits 
DBRA 106,602 ‚до next bit 


; NOTE: at this point D6 = -1. It is used as a flag to 
; kill leading zeros. 


58.5 Do2Digits 
MOVE .B D2,D1 
BSR.S Do2Digits 
MOVE .B D3,D1 
BSR.S Do2Digi ts 
MOVE.B 04,01 
BSR.S Do2Digits 
MOVE.B 05,01 
BSR.S Do2Digi ts 


;calculate length of string that was created 


63 MOVE А1,00 jend of string + 1 
SUB A0,00 ;beginning of string 
SUBQ.B 81,00 jminus 1 for length byte 


MOVE.B 00,(А0) 
MOVEM.L (5Р2%,А1/00-06 
RTS 


62 


0020 igi ts 
,convert BCD byte in D1 into 2 ASCII digits. 
;do most significant digit 
ROR 84 D1 
BSR.S  DoADigit 
)90 least significant digit 


ROL #4,D1 
DoADigit 
TST D6  ;have we had a non-zero digit yet? 
BPL.S  e6 
TST.B 01 jis this а leading zero? 
BEQ.S 67 
MOVEQ 80,06 ,print all zeros from now on 
66 ORI.B  *$30,01 ;covert BCD digit to ASCII 
MOVE.B 01, СА1)+ ,add it to the string 
SUB.B 01,01 
@7 RTS 


Listing 2 My Demo and Formatting Routines 


; ForaatDeno . asa 


; Written by Mike™ Scanlin 
; Slightly modif ied by D. Smith 
; for MacTutor. 19 OCT 1987 
; driver program to demonstrate DrawNumsInAString 


Include Тгарѕ.0 
Include ToolEqu.D 


Xref DrewNumsInAStr ing 


j;Quickdraw Equates Used: 


srcCopy EQU 0  ;copybits mode 
portBits EQU $2 ;port's bitmap [bitmap] 
portRect EQU $10 ;port's rectangle 
FormatDemo: 

РЕА -4СА5) ;іпіб everything 

_InitGraf jgraf port 

-InitFonts ,fonts 

-InitWindows ,"indows 

-InitMenus ,menus 

PEA Quit ;resume routine 

-InitDialogs ;dialogs 

-TEInit ;text edit 

MOVE.L  ЕҒЕҒ,00 

-FlushEvents ;С1еаг event queque 

-InitCursor ;cursor 

CLR.L -CSP) jreturned menu handle 


MOVE.W #1,-CSP) ;menu ID 1 

-Ge tRMenu ;get resource menu 

MOVE.L CSP), AppleHandle(A5) ;save menu handle 
MOVE.L (SP), -CSP);put back on stack 


CLR.W -CSP) ,add to menu end 
-Inser {Меги ;арр1е menu added 
MOVE.L ®’DRVR’, -CSP) дес das 
~AddResMenu ‚ада das to menu 
CLR.L -CSP) ;ret menu handle 
MOVE.W #2, -(SP) ;menu 10 2 
-GetRMenu ;get resource menu 
CLR.W -CSP) 800 to end 

_Inser tMenu jfile menu 

CLR.L -CSP) ;ret menu handle 
MOVE.W 83, -CSP) ;menu ID 3 

-Ge tRMenu дес resource menu 
CLR.W -CSP) зада to end 

-Inser tMenu message menu 
-DrawMenuBar ,do menu bar 
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CLR.L -CSP) ;,return window ptr -MoveTo ,move pen 


CLR.L -CSP) ;heap window record CLR -С(5Р) ;get ist operand 
PEA — wRect ,default rect size Random ja random number 
РЕА  wTitle  ;defeult tile MOVE СР +, D3 ;рор result 
MOVE $100, -CSP2 ; true for visible EXT.L D3 
MOVE ®noGrowDocProc,-CSP); window type CLR -CSP) ;get 2nd operand 
MOVE.L #-1,-CSP); window in front -Random ,8 random number 
CLR -CSP) 70 close box MOVE (SP )+, 04 ;pop result 
MOVE.L #3,-CSP) ;reference value EXT.L D4 
-NewW indow теке heap window MOVE.L 03,00 
ADD.L 04,00 ,eddition problem 
MOVE.L CSP),wPointer(A5) ;save window ptr MOVE.L D@,-CSP) ;ривһ result 
—SetPort зей graf port to window MOVE.L D4,-CSP)  ;push 2nd param 
—PenNormal ;init pen MOVE.L D3,-CSP) ;риѕћ 1st param 
MOVE #4,-CSP) ;any mono-spaced font will do PEA FormatString2 
—TextFont ,font JSR DrewNumsInAString ;format numbers 
MOVE 80 -(ӚӨР) ;normal ADD %20,УРо5(А5) ;reposition pen 
-TextFace ;Style SUB #1, count(A5) ;dec count 
MOVE # 12, -CSP2; 12 point type BNE 61 ‚до next problem 
-Техібіге ;512е ;do 5 division problems 
MOVE.L wPointer(A5), Аб MOVE #5, count (A5) ;count 
РЕА рог{ВесїСАЙ) @3MOVE #35, -CSP ) ;pen position 
-ClipRect ;set clip region MOVE vPos(A52,-CSP) ;реп position 
-MoveTo jset pen 
GetEvent : CLR -CSP) jget 20 bit random 8 
_Sys temTask ;check das -Random 
CR  -(SP) returned event CLR  -(9P) 
MOVE #- 1, -CSP); mask 811 events -Rendom 
РЕА X EventRecord(A5) X ;event record MOVE.L (SP)+,D3 
-GetNextEvent — ;get next event ANDI.L *$FFFFF,D3 
MOVE CSP2*,DO ;рор result 82 CLR -CSP) jget 16 bit random * 
ВЕ0.5 GetEvent ;9=null event Random 
MOVE What CA5), DØ ;what event? MOVE CSP2*,D1 
CMPI 81,00 ;mouseDown event? BEQ.S @2 ;don’t divide by zero 
BNE.S GetEvent ;no, try again MOVE.L 03,00 
DIVS D1,00 ;do division problem 
;handle а mouse down event MOVE.L 00,-(ӨР) ;push fixed point result 
CLR -CSP) іуе5, where mouse? MOVE D1, -CSP) 
MOVE.L WhereCA5), -CSP) EXT.L 01 
PEA = fndWindowCA5) MOVE.L D1,-CSP) ;push 2nd longint 
-F indWindow ;find window MOVE.L D3,-CSP) ;push ist longint 
MOVE (5Р2%,00 “рор result РЕА FormatString! 
CMPI 81,00 jin menu bar? JSR — DrewNumsInAString 
BEQ МегиВаг ;сһеск quit ADD . 520,vPos(A5) 
СМРІ 82,00 jin system window? SUB = #1, count (A5) 
BEQ System  ;do sysem stuff BNE 63 
CMPI 84 00 ;drag region? JSR  DoPic ;create quickdraw pic 
BEQ . DregIt  ;do drag BRA GetEvent 
CMPI 83,00 ;content region? 
BNE.S GetEvent ;no, ignore it DragIt: 
MOVE.L wPointer(A5), -(SP) — ;window ptr 
;do content click MOVE.L where(A5), -CSP) ;mouse 
CLR.L -CSP) мез, do click PEA . dregbounds ;bounds 
-FrontWindow ;window up? -DragW indow ,dreg it 
MOVE.L CSP)+, DØ ;pop result BRA — GetEvent 
CMP.L wPointerCA5), DØ ;our window up? 
BEQ Dolt мез, do click System: 
MOVE.L wPointer(A5), -(SP) X ;no, activate PEA EventRecord(A5) 
-SelectWindow jmake it front MOVE.L fndWindowCA5), -CSP) 
MOVE.L wPointer(A5), -CSP) _-System(] ick ;Support das 
-SetPort ;роіпі grafport to it BRA — GetEvent 
BRA GetEvent дес next click 
MenuBer : 
DoIt: CLR.L -CSP) ;menu choice 
;draw 10 strings in the window MOVE.L WhereCA5), -CSP) 
MOVE.L wPointer(A5), Аб | -MenuSelect | 
РЕА portRectCA2) ;деї wind port rect MOVE.W (SP)+,D5 jmenu 
-EreseRect ,erase port rect MOVE.W (SP2*,D6 ;iten 
MOVE #38, vPos(A5) ;Ѕеї pen coord CLR.W -CSP) 
;do 5 addition problems -HiLiteMenu 
MOVE #5, соџп{СА5) 25 problems count 
@1MOVE #56, -CSP) бес pen coord CMP #1,D5 
MOVE vPos(A5),-CSP) BEQ AppleMenu 
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CMP #2,D5 
BEQ FileMenu 
BRA GetEvent 


App leMenu : 
CMP #1,D6 
BEQ About 


PEA grafporttempCA5) ,do das 
-GetPor t 

Move.L AppleHandleCA5), -CSP) 

Move.W D6,-CSP) 

PEA DeskName(CA5) 

-GetItem дес da name 
CLR -CSP) 

PEA DeskName(A5) 

-OpenDeskAcc ;start up da 
Move (SP)+, 00 ;result 
MOVE.L grafporttempCA5), -CSP) 
_ЗеіРогі 

BRA GetEvent 


About: 
Move.W #5, -CSP) 
-SysBeep ;Sorry charlie! 
BRA GetEvent 


FileMenu: 
Quit: 
-ExitToShe11 


DoPic: 
CLR.L -CSP) ;Save pic of screen 
MOVE.L wPointerCA52, -CSP) 
-GetWindowP ic ;get current pic 
MOVE.L CSPO*, Ай 
MOVE.L A0, -CSP) 
-KillPicture sg it 
CLR.L -CSP) 
MOVE.L wPointer(A5), Аб 
РЕА portRect(A2) 
-OpenPicture ;Open new pic 
MOVE.L CSP)+, Аб 
MOVE.L wPointer(A5), -CSP) 
MOVE.L AØ, -CSP) 


-SetWindowP ic jset in window rec 
MOVE.L wPointerCA5), Аб 
PEA portBitsCA0) бес up copybits 


РЕА portBits(A0) 
РЕА portRect(Ag) 
PEA portRectCA0) 
MOVE .W ®srcCopy, -CSP) 


CLR.L -CSP) 

_СоруВіїѕ сору screen to pic 
-ClosePicture ;close pic 

rts 


; Deta structures - Constants 


wRect DC 60,80,300,420 
dragbounds DC 20,40,330,492 
wlitle DC.B 17, “Formatted Numbers’ 


злобе: format strings must end with а zero byte 
FormatString!  DC.B *\1, 10 / \i,7 = \f,7.5’,8 
FormatString2 OC.B‘\i,7 + \i,7 = M,T',0,0 


; Data structures - variables 


vPos DS 1 
count DS 1 
wPointer — DS.L 1 
fndWindow 0511 
AppleHandle 05.1 1 


64 


DeskName DS.L 1 
grafporttemp DS.L 1 
EventRecord DS.W9 
What DS .W 1 
Message 05.11 
When 05.11 
Where DS.L 1 
Modifiers DS .W 1 


Listing 3 Formatting Library for Numbers 


; DrawNumsInAStr ing.asm 
by Mike™ Scanlin 
Include Traps.D 


Xref DrawNums InAStr ing, NumToStr ing,F ixPtToStr ing, FormNumS tring 
Xref GetANumber 


Draw a string that may contain implicit formatted numbers. 
input: stack contains numbers that will be needed and a 
pointer a string. The numbers should be pushed on the stack in 
order from last to first (so they can be poped off in order 
from first to last). The last thing to be pushed on the stack 
is the string pointer. Each formatted number within the input 
string begins with a ‘\’ and then either an ‘i’ (for longints) 
or а ‘f’ (for а fixed point number). For fixed points, first 
push the fixed point number, then the divisor to be used to 
calculate the remainder. The formatting after the ‘i’ or ‘f’ 
is the same as for the FormNumString routine. output: a string 
is drawn А0,00 are trashed. 


MOVEM.L A0-A3/D1-D2, - CSP) 
LEA 28С(5Р),АЗ ;point to first parameter 
MOVE.L — A3,-(SP) ;save initial position 
MOVE.L САЗ)+,А2 string pointer 

@1MOVEQ “0,00 
МОМЕ. В СА2)+,00 


BEQ.S e 10 ,end of string found 
CMPI.B 44700 jis it a number? 
BEQ.S 62 

MOVE  D0,-CSP) 

-DrewChar 

BRA.S 6@1 


зне got а number to format 
e2LEA scratch, Ad 
MOVE.B СА2)+,00 


CMPI.B #i’ DØ ;18 it a longint? 

BNE .S 84 
;handle integers 

MOVE.L САЗ)+,00 дес longint 

JSR — NunmToString 

BRA.S e5 ;go format it 
e4CMPI.B “7” 00 ;is it а fixed point? 

BNE .S e1 jif not, ignore it 


;handle fixed point 

MOVEA.L A2,A1 
;find out how many decimal places should be passed to 
; FixPtToString 


MOVE.B СА1)+,00 ;Skip comma, if present 
CMPI.B 87” D8 
BEQ.S 64.1 
SUBA 81,1 
64.1JSR Сбе(АМ/тбег 
BMI.S e1 ;no quotient present 


MOVE.B (А12%,00 
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CMPI.B 87.” 00 
BNE.S 84.2 
JSR GetANumber 
MOVE 00,02 
BPL.S 64.3 
64.2 MOVEQ #0,02 
84,3 MOVE (А32%,01 
MOVE.L САЗ)+,00 
JSR  FixPtToString 
;%9 the formatting 
65MOVEA.L A2,A1 
JSR . FormNumString 
MOVEA.L A1,A2 
MOVE.L — A8,-CSPD 
-DrawStr ing 
BRA.S e1 
810 SUBA.L — (SPO*,A3 
MOVE АЗ,00 
MOVEM.L CSP)+,D1-D2/A9-A3 
MOVE.L (CSP)+,Ad jget return addr 


jno remainder 
;get divisor 
jget fixed point num 


,eddr of format string 


jpoint past format string 


;calc len of params 


ADDA 00,5Р ; length of parameters 
JMP (Ад) 
Scratch DCB.B 40,0 


; FixPtToString.asm 
; by Mike™ Scanlin 
Xref FixPtToStr ing, NunToString 


; convert а 32 bit fixed point number into а pascal 
; string. 

; input: 00 fixed point number 

; 01 16 bit divisor used when DØ was calculated 

; 02 8 of digits after decimal point (02-0 for no 
; dec point) 

; M points to a space of at least (8 + D2) bytes 
; Output: Аб points to pascal string 


MOVEM.L 00-О3/А1,-(5Р) 
MOVE.L 00,03 ,Save quotient & remainder 
EXT.L 00 ;Sign extend quotient 
JSR NumToStr ing 
jif а = 0 and the result should be < Ø, we^11 have to 
; edd а minus sign. 
;(NumToString won^t know about it, since all it sees 15 
; а zero quotient) 


TST D3 ;а = 0? 

BNE .S eo 

TST.L D3 ; check remainder 

BEQ.S eg 24 & r both zero 
jif r & divisor have the same sign, then result will 
; be>? 

EXT.L D1 

MOVE.L 01,00 

EOR.L 03,00 

BPL.S 80 


MOVE.B %%-” (А0) 
MOVE.B 870,2СА0) 
MOVE.B 82 (А0) ;пен length 

80 Т5Т 02 90 we want а decimal point? 
BEQ.S 86 
MOVEQ 80/00 
MOVE.B (А0),00 ;length of quotient 
LEA 1(А0,00),А1;епд of string + 1 
MOVE.B — 8^." (AD* 
TST.L D1 jmake divisor positive 
BPL.S ei 
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NEG .L D1 
e1TST.L D3 jmake remainder positive 
ВРІ .S @2 
NEC .L D3 
@2SWAP 03 
ANDI.L — *"$FFFF,03 ;isolate remainder 
5080 #1,D2 ; loop control 


@3 ADD .L 03,03 
MOVE.L 03,00 


;mult r by 10 


ADD.L 00,00 ;4x 
ADD.L 00,00 ;8х 
ADD.L 00,03 ;10x = 8x + 2x 


MOVEQ — $'/0',D0 
e4CMP.L 01,03 


;init digit 
jis 10г > divisor? 


BLT.S e5 
ADDQ %1,00 ;increese digit 
SUB.L 01,03 ;Subtrect divisor 
BNE .5 84 
65MOVE.B 00, СА1)+ зада to string 
DBRA  D2,e3 
MOVE А1,00 ,calc length of new string 
SUB Ad, DØ 


SUBQ.B 81/00 

MOVE.B 00, CAB) 
@6MOVEM.L (SP)+,A1/D8-D3 

RTS 


jminus 1 for length byte 


; FormNumS tring. asm 
+ by Mike™ Scanlin 
Xref FormNumS tr ing, GetANumber 


ForaNunString 


; format the string representation of a number Cinteger 
; or real) according to a format string. 
; input: А0 points to string of a number (which should 
; be in а space big enough for formatting result) 
A1 points to format string 
syntax of format string is І7,710/011”. 710140111 
where '^ denote а constent char and d denotes 


there is no length byte for these strings. 
valid strings invalid strings 
3 


230. (230 too big [99 max) 
4.0 or 4 ‚0 (need а d before '.') 
3.4 ‚4 (need а d between ‘,.’) 


‚12.20 8.123 (123 too big) 
; Output: Аб points to formatted string of a number 
Al points to first byte after format string 


, 
, 
) 
) 
) 
à 
, 
, 
; а digit '0^..'9' 
) 
4 
) 
, 
) 
, 
) 


MOVEM.L D@-D5/A2,-(SP) 
CMPI.B 87” (AD 


BNE.S ёб 
ADDA 81 A1 
,do commas 


¿first find out if а decimal point in the string 
MOVEQ 10,00 
MOVE.B (А0),00 ;length of string 
MOVE 00,02 ,Save in case it’s and int 
SUBQ 81/00 ; loop control 
; DØ counts how many digits from the end of the string 
; to the decimal point Cincluding the decimal 
; point — which is why it starts out as 1 and not 0). 
; If the number is an int, then D0-0 
MOVEQ 81/01 
e1CMPI.B %”.” 1(А0,00)  ;dec point, it’s а real 
BEQ.S @2 
ADDQ 81/01 
DBRA 00,01 


65 


21478 an integer 


MOVE 
MOVEQ 


02,00 
«0,01 


‚пон add some commas 


@2 MOVE D1,D5 jsave length of fraction 
MOVEQ #3,D2 ;* of digits until next comma 
SUBQ 81,0 

63 ADDQ 81,01 ; total len, from end to cur pos 
SUBQ 81,02 
BNE.S @5 
MOVE 00,03 
MOVE.B (А0,00),00 
BSR IsItADigit ;test next digit 
BNE.S e6 
MOVE 03,00 

;move some chars, add а comms, increase string length. 
MOVE D1,D4 ; loop control 
SUBQ 81,D4 
LEA 1(А0,00),А2 

04М0УЕ.В (42,04), 1(А2,04) 

ОВКА 04,04 

MOVE.B %””/ (А2) 

ADDI.B — *1,CA0D 

ADDQ 81/01 Рог the comma 

MOVEQ 83,02 ;reset counter 
65 DBRA 00,63 


дес next byte of format string 


86 BSR.S GetANumber ;00 = q 
BMI.S 616 ‚гю q provided - leave 
MOVEQ %0,02 
MOVE.B (A®),D2 j length of string 
MOVE 02,01 
SUB 05,01 ;01=1еп of quotient now 
SUB 01,00 
BMI.S 60 
BEQ.S 61 
ADD.B 00,(А0) ;increase length by DØ spaces 
;add 00 of preceeding spaces 
@7LEA 1(А0,00),А2 
5080 81,02 
e8MOVE.B 1(ҮА0,02),СА2,02) 
DBRA 02,68 
5080 81/00 
e9MOVE.B %” ',1CA0,D0) 
DBRA 00,69 
;9 remainder 
010 CMPI.B %”7” (А1) 
BNE.S 616 
ADDA *1,A1 
‚таке sure there is а decimal point already 
LEA 1(А0),А2 
MOVEQ 80,00 
MOVE.B (А0),00 
5080 81/00 
611 CMP.B %”” (А2) 
BEQ.S 612 
DBRA 00,611 
MOVE.B 47.” (А2)+ 
ADD.B = #1, CAB) 
@12 BSR.S GetANumber 
BMI.S 616 ;no г provided – leave 


; 00 is how many digits they want. D5 is 
; what we’ve already got. 


@13 SUBQ 

014 CMP 
BEQ.S 
BPL.S 
SUB.B 
BRA.S 


615 MOVE.B 


ADD.B 
ADDQ 
BRA.S 
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81,05 

05,00 

616 

015 

81 (А0) 

613 

870" (A2,05) ;add а zero 

81,СА0) 

81,05 

614 


616 MOVEM.L (SP)+,A2/D8-D5 
RTS 


convert а one or two digit 
its numerical form 


didn’t point to a digit) 


we We We We We We We Ww 


MOVEM.L 01-02,-С5Р) 
MOVEQ —— "0,00 
MOVE.B СА1),00 

e1BSR.S — IsItADigit 
BEQ.S 62 
MOVEQ — %-1,00 
BRA.S е4 

@2ADDA — *1Al 
MOVE 00,01 
MOVE.B СА1),00 
BSR.S — IsItADigit 
BEQ.S ё 
MOVE 01,00 
BRA.S 64 

e3ADDA — *1,1 
ADD D1,D1 
MOVE 01,0 
ADD 02,02 
ADD 02,02 
ADD D2,D1 
ADD 01,04 


@4MOVEM.L (SP)+,D1-D2 
TST 00 
RTS 


; If the ASCII byte in DØ is 
value (0..9) 


we We We We 


flags are set. 
СИРІВ — "'0',DO 
BLT.S 61 
CMPI.B — *'9',00 
BGT.S 61 
SUBI.B — ?*'0',D0 
MOVE 8- 1, CCR 
RTS 

e1MOVE 89, CCR 
RTS 


NumToStr ing.asm 


| 
; by Mike™ Scanlin 
; 


ASCII integer into 


input: Al points to digit(s) 
output: 00 is the decimal equivalent (-1 if А1 


А1 points to byte after digit(s) 
Z end М flags reflect the value of 00 


smultiply first digit by 10 


‚абд to second digit 


in ‘6’..’9° it’s 


is returned in DØ. If DØ is a digit, all 


;set all flags 


;clear all flags 


an alternative to _NumToString 


Xref NumToStr ing 


; convert a 32 bit integer into a pascal string 


Аб points to a space of at least 12 bytes 
; Output: Аб points to pascal string 


д 
input: 00 longint 


MOVEM.L 00-04/А1-А2,-(9Р) 
LEA 1(А02,А1 


;Skip length byte 
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TST.L 00 ;is number zero? DC.L $9E207802, $80204402, $40204404, $20213808 


801.5 @2 DC.L $18000030, $O7FFFFCS, $00000000, $00000000 
BMI.S 61 DC.L$FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
MOVE.B — 8/9',(AD* ,Special cese for zero ОС. $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
BRA.S 68 DC.L $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
e1M0VE.B — t'-^,CAD* ;give string 8 minus sign DC.L $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
NEG.L 00 ;m&ke number positive ОС. $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
@2LEA PowersTable,A2 DC.L $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
MOVEQ #1,D3 ;set leading zeros flag DC.L $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
MOVEQ #89,D4 ; loop counter DC.L $FFFFFFFF, $FFFFFFFF, $FFFFFFFF, $FFFFFFFF 
@3MOVE.L  (A2)+,D2  ;get a power of 10 
MOVEQ  8^0',0]1 sinit digit . ALIGN 2 
e4CMP.L 02,00 218 8 > power of 10? RESOURCE ‘MENU’ 1 ‘APPLE’ 
BLT.S 65 DC.W1 menu id 
ADDQ 81,01 j increase digit 00.40  ;width holder 
SUB.L 02,00 jsubtract power of 10 DC.W9 X ;height holder 
BNE.S 64 0010 ;геѕоџгсе id holder 
85 TST D3  ;have we had a non-zero digit yet? DC.L $1FB ;flags enable 811 except 2 
BEQ.S 66 DC.B1 ;title length 
CMP.B #79’, D1 jis this а leading zero? DC.B20 ;title apple symbol 
BEQ.S 6 
MOVEQ #9 D3 sprint all zeros from now on DC.B22  ;menu item length 
e6M0VE.B D1,CA1)+ DC.B ‘About this program... * 
ет DBRA 04,63 06.80 ;го icon 
88 MOVE А1,00 ;celc length of new string DC.B@ ;по keyboard equiv 
SUB А0,00 00.80  ;marking char 
SUBQ.B 81/00 jminus 1 for length byte 00.80 =;style of item text 
MOVE.B 00, САЙ) 
MOVEM.L С5Р)+, А 1-А2/00-04 DC.B2 ;тепи item length 
RTS DC.B '-^ 
06.80  ;no icon 
PowersTable: DC.B®  ;no keyboard equiv 
DC.L 1000000000 00.80 marking char 
DC.L 100000000 06.80 әуе of item text 
DC.L 10000000 
DC.L 1000000 005.80 ;end of menu items 
DC.L 100000 
DC.L 10000 . ALIGN 2 
DC.L 1000 RESOURCE ‘MENU’ 2 ‘FILE’ 
DC.L 100 DC.W2 ;тепџ id 
DC.L 10 00.40 X ;width holder 
DC.L 1 DC.W8 X height holder 
REN CA лт ыны р Se LIC DEC 0010 ;геѕоџгсе id 
; Resource File DC.L $1FF ; flags 
RESOURCE ‘FRED’ 0 ‘IDENTIFICATION’ DC.B4 ;title length 
DC.B 14, ‘Format Program’ DC.B ‘File’ ;title 
„ALIGN 2 DC.B6 j;menu item length 
RESOURCE 'BNDL^ 128 ‘BUNDLE’ DC.B ‘Quit/Q’ 
00.80  ;no icon 
DC.L ‘FRED’ ;name 00.80  ;no keyboard 
DC.W 0, 1° ;data 0С.В0 X ;no marking 
DC.L 'ICN' ^ ; icon map 06.80 ;54Ле 
DC.W0 ;mapping- 1 
DC.WØ, 128 ;mep 0 to 128 0С.80 ;end of menu items Listing 4 The Link File 
DC.L ‘FREF’ ;file ref . ALIGN 2 ] 
DC.W0 ;maps-1 RESOURCE 'MENU^ 3 'MESSAGE" ) 
DC.W0,128 ;map Ø to 128 00.83  ;menu id /OUTPUT Format Demo 
DC.W8 X ;width holder 
RESOURCE 'FREF^ 128 'FREF 1’ DC.W@ height holder FormatDemo 
0010 resource id NumToStr ing 
DC.B 'APPL^,0,0,0 DC.L $1F8 ;flags - DISABLE FixPtToString 
DC.B 16 ;title length FormNumStr ing 
„ALIGN 2 DC.B ‘Click in Window ° ;title DrewNums InAStr ing 
RESOURCE ‘ICN®’ 128 ‘MY ICON’ 
DC.BØ ;menu item length /TYPE ‘APPL’ ‘FRED’ 
DC .L $20000006, $00000000, $O7FFFFCO, $18000030 DC.B '' /BUNDLE 
DC.L %202038Е8, $40604514, $80204412, $80204422 0С.В0 ‚по icon /RESOURCES 
DC.L $80204441, $80204481, $802139F1, $80000001 DC.BØ ;no keyboard Format rscs 
DC .L 980000001, $80F81021, %80103061, $8020 10А1 DC.BØ ;по marking 
DC.L$80701121, %800811Ғ1, $80881021, %80711021 DC.B® ;style $ 


DC .L 980000001, $80201801, $80602001, %80204001 


DC.B@ ;end of menu items 
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The Midi Mac 
A Midi Demo for the Mac II 


Here we are back in MIDI land again. This is a continuation 
of the July 1987 article in which we bacame familiar with what 
MIDI is all about, and looked into some of the low level routines 
that are necessary to work with MIDI on the Macintosh. 

Now, probably whatI didn't tell you last time was that these 
low levelroutines were designed to work with LightSpeed Pascal 
from Think Technologies. I have found that this is the easiest 
development system for people just starting to program the 
Macintosh because of its unique source level debugging features. 
Also, I have found the Pascal language to be the best choice 
among languages available for the Macintosh because the 
Macintosh was designed with the Pascal language in mind. 
Because of this all of the documentation is written with a Pascal 
syntax (Inside Macintosh, Macintosh Revealed, etc.). 

As a result of this built-in bias, if any other language than 
Pascal is chosen as a development tool, a great deal of time is 
typically spent just translating from the Pascal documentation to 
whatever language you have decided to use. The moral of the 
story is, if you are just starting out programming the Macintosh, 
you would be doing yourself a big favor by choosing Pascal as 
your development language, ‘nuff said. 


The Apple Music Fair 


On July 10th Apple had an in-house party to let its employ- 
ees find out more about music programs for the Macintosh. It was 
agreat party, with food and drinks in the courtyard of the DeAnza 
3 building. About a dozen or so companies with music products 
for the Macintosh were present, showing their wares, and there 
was even a presentation by Alan Kay on the future of computers 
and music. 

I was impressed by the fact that Apple is making an effort to 
get its employees excited about the musical possibilities of the 
Macintosh computer. The Mac has become the defacto standard 
for MIDI controllers. If you attend one of the biannual NAMM 
shows (which is where all of the new musical products are 
exhibited) you will find that the Macintosh has taken over as far 
as musical computers go. I just wish Apple would go a little bit 
further with their support of MIDI. For instance, I know that there 
are MIDI routines built into the new ROM's on the Macintosh II, 
but I can't get anyone at Apple to tell me what they are. Now, 
obviously, someone there knows what the routines are, after all, 
someone had to write them in the first place, right? But, for some 
reason, Apple is notreleasing the information just yet. I hope this 
changes soon, as I would like to be using ROM routines instead 
of having to write all of my own code, but I guess I will just have 
to wait a while (sigh). 
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By the way, I heard that copies of the July issue of MacTutor 
are making the rounds at Apple and I have gotten inquiries about 
the MIDI routines from some Apple employees. Maybe I can stir 
up enough interest at Apple to get them to come through with 
some information (are you listening, guys?). 


Whoops! 


Unfortunately, there was a slight oversight on my part in the 
program listings that were printed in July that caused a bug in the 
interrupt handlers. If you are using the low level routines in a 
program that uses input from the Macintosh keyboard, the status 
register can become corrupted by the MIDI interrupt routines and 
the computer will think that it is getting a never-ending string of 
keystrokes from the ASCII keyboard. I geta string of lower case 
“с”, but othere people have reported getting lower case “5”, 

Anyway, the problem is that I neglected to save and restore 
the status register in the interrupt routines, so you need to add the 
following two lines to the four interrupt handlers (i.e. TxIntHandA, 
TxIntHendB, RxIntHandA, and RxIntHendB): 

This should be the first line at the beginning of each routine: 


MOVE SR,-CSP) 

then, replace the line 
ANDI *$F8FF,SR 

at the end of each interrupt handler with the following line 
MOVE (SP)+,SR 


This change keeps the status register intact instead of chang- 
ing its value after the interrupt routine has executed. Sorry if this 
error has caused anyone a great deal of hair pulling. 


New Changes to LLMIDI 


There are also a couple of additional routines that I have 
added to the library since it was published. The revised routine 
library is available on the source code disk for July, so if you just 
buy that you will save yourself an awful lot of typing. Also, there 
is the distinct possibility that if you do type the listings in yourself 
that you will make a typo and it will get flagged as an assembly 
error. The listings on the source code disk have been assembled 
with MDS without any errors being flagged, so if you are 
showing an error it is probably a typo. 

Anyway, the new additions to the library have to do with 
filtering out “active sensing” MIDI bytes from the data stream, 
and also adding a MIDI thru function that echoes the incoming 
MIDI data on either the same port or the opposite one. 
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Active Sensing 


This is a data byte that is sent out by some controllers every 
300 milliseconds or so that lets receiving equipment know that 
everything is hunky dory. Mostly, it just gets in the way of 
whatever you might be trying to do with the MIDI data stream, 
so the best thing to do is just filter it out before it gets placed in 
the buffer. A slight change to the RxIntHand routines is all that 
is necessary to do this, and it consists of a grand total of two lines 
of assembly code. 


MIDI Thru 


The MIDI thru capability is pretty easy to add too. It's 
another change to the RxIntHand routines that calls either 
TxMIDIA or TxMIDIB depending on the variable ThruFlagA or 
ThruFlagB. In order to set the variables two routines had to be 
added to the library: MIDIThruA and MIDIThruB. 


The new routines 


XDEF MIDIThruA 
XDEF MIDIThruB 
ThruFlagA DC 0 
ThruFlagB DC 0 


; MIDI thru flag for modem port 
; MIDI thru flag for printer port 


; This routine lets you do a MIDI Thru function 
; The Thrucode is: 

; Ø = No thru function 

; 1* MIDI thru on the same channel 

; 2 = MIDI thru on the opposite channel 


; Procedure MIDIThruACThrucode : 
MIDIThruA 
LEA ThruF lagA, Ad 
MOVE 4(SP), CAG) 


integer); 


; point to the flag 
set the flag 


д 
MOVE.L (ӨР2%,АЙ ; save the return address 
ADDQ #2,5Р ; move past the parameter 
MOVE.L A@,-CSP) ; put the return address back 
RTS ; and return 


This is the interrupt routine for receiving through the 
modem port. It places the counter value and the MIDI byte in 
а circuler queue to be accessed later by the application. 
When the system gets this far, AØ contains the SCC base read 
Ctl address and А1 contains the SCC base write Ctl address 
for this channel. The data addresses are offset by 4 from 
the control addresses. 00-03/А0-АЗ are already preserved, 50 
they may be used freely. 


wee We We We We We We % о 


RxIntHandA 
MOVE SR,-CSP) 


save status register 
ORI 5*$0300,SR 


disable interrupts 


me We 


ӨЗ MOVE #4 Dd 
CLR.L 01 


get data offset 
prepare for data 


MOVE.L (SP), (SP) Delay 
MOVE.B 0(Ү0,002,01 read data from SCC 
MOVE.L СР), СР) Delay 


we We We We We voe 


CMPI %ҒЕ,01 
BEQ e? 

LEA ThruFlagA,A1 : 

CMPI #1, (А1) ; check for MIDI Thru 
BNE 64 

MOVE D1,-CSP) ; put data on the stack 


filter out acitve sensing 
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BSR TxMIDIA 


LEA ThruFlagA A1 
CMPI #2, (А1) 

BNE 05 

MOVE D1,-(SP) 
BSR TxMIDIB 


LEA RxQueueA, А2 
LEA RxByteInA, АЗ 
MOVE (АЗ),00 
LEA Counter, A3 
MOVE.L (A3),D2 
LSL.L #8,02 
ADD.L 02,01 
MOVE.L 01,0(А2,00) 
LEA  RxQEmptyA, A3 
MOVE #@,CA3) 
ADDQ 4,00 
CMP %%400,00 
BNE e1 
MOVE 80,00 

61 ТЕА RxByteInA,A3 
MOVE 00, САЗ) 


62 BIST.B #0, (А0) 


BNE 63 


MOVE (SP)+,SR 
RTS 


“е We "e We We We We We We 


TxIntHandA 
MOVE SR,-(SP) 
ORI %%0300,58 


LEA TxQEmptyA,A3 
TST.B (A3) 
BEQ 61 
MOVE.B #$28,(А1) 
MOVE.L СР), (SP) 
BRA TxIExitA 

@1 LEA TxByteOutA, АЗ 
MOVE САЗ),00 
LEA TxQueueA, А2 
MOVE #84,D1 


MOVE.B 9(A2,D8),0(A1,D1) 


MOVE.L ($Р),С$Р) 
ADDQ 51,00 
CMP *$100,00 
BNE 062 
MOVE "2,00 

62 LEA  TxByteOutA, АЗ 
MOVE 00, САЗ) 
LEA  TxByteInA, A3 
MOVE САЗ),01 
CMP 00,01 
BNE TxIExitA 
LEA TxQEmptyA, A3 
MOVE $FFFF,CA3) 


TxIExitA 
MOVE (SP)+,SR 
RTS 


we We we 


we Wo 


“е We We We We We We We We We We 


we We we 


we We 


send it out port A 


check for MIDI Thru 


put data on the stack 
send it out port B 


point to queue 

get the address 

get offset to next cell 
get the address 

put counter value in D2 
shift counter one byte 
combine counter and data 
put longword in queue 
get the address 

reset queue empty flag 
update index 


get the address 
is there more data? 
do it again if there is 


restore status register 
end return 


This is the interrupt routine for transmitting a byte 
through the modem port. It checks to see if there is any 
data to send, and if there is it sends it to the SCC. 
there isn’t it resets the TBE interrupt in the SCC and 
exits. When the system gets this fer, Ад contains the SCC 
base read Ctl address and А1 contains the SCC base write Ct] 
eddress for this channel. The data addresses are offset by 4 
from the control addresses. D9-D3/A0-A3 are already pre 
served, so they may be used freely. 


we We 


disable interrupts 


get the address 
Is queue empty? 
if not brench 


Delay 
end exit 
get the address 


point to queue 
get data offset 
write data to SCC 
Delay 

update index 


we ee We We We We We We We We We Be Be 


; get the address 
; get the address 


is TxQueue empty? 
if not exit 

get the address 
if empty set flag 


wee We We We 


vwo 


end return 


we 


If 


save the status register 


if so, reset TBE interrupt 


get index to next data byte 


restore status register 
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This routine lets you do & MIDI Thru function 
The Thrucode is: 

Ø = № thru function 

1 = MIDI thru on the same channel 

2 = MIDI thru on the opposite channel 
Procedure MIDIThruBCThrucode : integer); 


we We Be We We We 


MIDI ThruB 


LEA ThruFlagB, Ag 
MOVE 4(SP), CAD) 
MOVE.L (SP)+,Ad 


point to the flag 
set the flag 
save the return address 


we We We We We We 


ADDQ #2,SP move past the parameter 
MOVE.L А0,-(ӨР) put the return address back 
RTS and return 


This is the interrupt routine for receiving through the 
printer port. It places the counter value and the MIDI byte 
in a circular queue to be accessed later by the appl- 
ication. When the system gets this far, Ай contains the SCC 
base read Ctl address and А1 contains the SCC base write Ctl 
address for this channel. The data addresses are offset by 4 
from the control addresses. 00-03/А0-АЗ are already pre- 
served, so they may be used freely. 


%“ - We We '— We C We We 


RxIntHandB 


MOVE SR,-CSP) 
ORI *$0300,SR 


63 MOVE %4,00 


CLR.L Di 


"eo We 


save status register 
disable interrupts 


get data offset 
prepare for data 


MOVE.L СР), СР) Delay 
MOVE.B 0(Ү0,002,01 reed deta from SCC 
MOVE.L (SPO,CSP) Delay 


CMPI %ҒЕ,01 

BEQ @2 

LEA ThruFlagB, A! 
CMPI #1, (А1) 

BNE 04 

MOVE D1,-CSP) 
BSR TxMIDIB 


Be Be eo We We Be 


we 


we Ge 


filter out acitve sensing 


check for MIDI Thru 


put data on the stack 
send it out port B 


84 
LEA ThruFlagB, A1 
СМРІ #2,(A1) ; Check for MIDI Thru 
BNE 65 
MOVE D1,-CSP) ; put data on the stack 
BSR TxMIDIA ; send it out port A 

@5 


LEA RxQueueB, А2 
LEA RxByteInB, АЗ 
МОМЕ (АЗ),00 

LEA Counter ,A3 
MOVE.L (A3),D2 
LSL.L #8,D2 
ADD.L 02,01 
MOVE.L D1,0(A2,D0) 
LEA RxQEmptyB, АЗ 
MOVE #0, САЗ) 
ADDQ 4,00 

CMP %%400,00 

BNE @1 

MOVE #0,00 


@1 LEA RxByteInB,A3 


MOVE 00, САЗ) 


62 BIST.B #0, САЙ) 
BNE @3 


MOVE  (SPO*,SR 
RTS 


we We "e We We We We We We We We 


we We me 


we We 


point to queue 

get the address 

get offset to next cell 
get the address 

put counter value in D2 
shift counter one byte 
combine counter and data 
put longword in queue 
get the address 

reset queue empty flag 
update index 


get the address 
is there more data? 
do it again if there is 


restore status register 
end return 


; This is the interrupt routine for transmitting a byte 


; through the printer port. 
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It checks to see if there is апу data to send, end if there 
is it sends it to the SCC. If there isn't it resets the TBE 
interrupt in the SCC and exits. When the system gets this 
far, Аб contains the SCC base read Ctl address and А1 
contains the SCC base write Ctl address for this channel. 
The data addresses are offset by 4 from the control addr- 
esses. D0-D3/A2-A3 are already preserved, so they may be 
used freely. 


we "eoe We We We We We We 


TxIntHandB 
MOVE SR,-CSP) 


save status register 
ORI 5$0300,SR 


diseble interrupts 


me We 


LEA TxQEmptyB,A3 
TST.B (АЗ) 
BEQ 61 
MOVE.B #$28,(А1) 
MOVE.L (SP), (SP) 
BRA TxIExitB 

61 LEA TxByteOutB, АЗ 


get the address 

Is queue empty? 

if not branch 

if so, reset TBE interrupt 
Delay 

end exit 

get the address 


MOVE (АЗ),00 get index to next data byte 
LEA TxQueueB, A2 point to queue 
MOVE #4,D1 get data offset 


MOVE.B 0СА2,00), 0СА1,01) 
MOVE.L (SP), (SP) 

ADDQ #1,DØ 

СМР *$100,00 


write data to SCC 
Delay 
update index 


we We We We We We We We We We We We We 


@2 LEA TxByteOutB, АЗ 
MOVE 00, САЗ) 
LEA TxByteInB,A3 
MOVE САЗ),01 
CMP 00,01 
BNE TxIExitB 
LEA TxQEmptyB,A3 
MOVE 8$FFFF, САЗ) 


get the address 


we 


get the address 


we 


is TxQueue empty? 
if not exit 

get the address 
if empty set flag 


we We We e 


TxIExitB 
MOVE (SP)+ SR ; restore status register 
RTS ; end return 


The World's dumbest MIDI program 


This brings us to an actual example of how to use these 
routines in a typical program. For the example program I have 
chosen to make the Macintosh into the worlds most expensive 
MIDI thru box. Actually, it reminds me of when I first got my 
Macintosh in 1984 with just MacPaint and MacWrite available. 
I used to call it the $2,000 etch-a-sketch (ha ha). 

At any rate, the demo program MIDI Shell lets you test out 
the various modes of MIDI thru by using menu selections. I also 
added some of my preferred techniques for writing applications 
in general, such as including a Transfer... menu item in the file 
Menu, and using an About... dialog box that doesn't get in the 
user's way. 

What I mean by that last statement is that most About... 
boxes that I see force you to click on an OK button or something 
in order to continue working in the program. Now, there are some 
cases where you don't have to click in the dialog box itself, but 
you can't just go up and make a normal menu selection because 
youhavetoclick once justto get rid of the dialog first (the finder's 
About... box is an example of this way to handle it). My feeling 
is that the optimum way to deal with the About... dialog box is to 
make it possible to use the program without having to concern 
yourself with getting rid of the dialog box first. This is accom- 
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plished by using the scheme presented in the DoAbout proce- WHILE NOT Button DO 


dure: -— | | | DisposDialog(theD10g); 

The Transfer... item in the File menu is one that I wish were SetPortColdPort); 
in every Macintosh program. It makes life much easier by not END; 
making the user have to go back to the Finder all the time. PROCEDURE LaunchIt (mode : integer; 
Considering that it is so simple to implement, I end up using it in VAR fName : Str255); 
every program I write. INLINE 


$204F, (movea.1 ат, ай; (ай) is string ptr, 4Ca0) mode) 
%АОҒ2; (Launch) 


More ways to skin the cat 
Now, I should probably point out at this time that there are еу ва pester; 
other ways to deal with MIDI input and output besides the where : Point; 
interrupt method that I have described so far. There is also a reply : SFReply; 
technique known as polling. thefNene : $tr255; 
Polling is done by dropping all other considerations and just textType : SFTypeL ist; 
constantly looking at the receive register of the SCC chip to see IN 


where.h := 80; 
where.v := 55; 


if thereisanything there. While it may sound really dumb at first, 


polling can be very useful in certain circumstances, like when textType[8] := ‘APPL’; 
you know exactly when a large amount of MIDI data is going to oh BA ды, Null, NIL, 1, textType, NIL, reply); 
. . | . . . reply 
arrive. This happens in programs like patch librarians, for IF NOT good THEN 
example. thefNeme := Null 
Now, of course, doing polling requires an entirely different ELSE 
set of low level routines. Next article ГІ show you some of these а Й РИ 
routines and how to write a simple patch librarian with them. vRef :- vRefNum ` 
Then, in a later article, I'll come back to the interrupt driven END; 
library to look at writing a ‘Stone Age Sequencer’. Until then, IF co NIV THEN 
happy coding. Done := true; 
IF SetVolCNIL, vRef) = noErr THEN 
BEGIN 
( Kirk Austin, 7/12/87 ) ResetSCCA; 
( This is an example program that illustrates the ) ResetSCCB; 
(following techniques: ) QuitTimer; 
( My preferred method for handling the about box ) LaunchIt(®, thefName) 
(The use of the transfer command in the file menu } END; 
(The use of the LSPMIDI library including MIDIThru) : END 
ND; 


PROGRAM ShellExemple; 
PROCEDURE ProcessMenu С codeWord : Longint); 


USES ( hendle menu selections) 
LSPMIDI; VAR 
( Global Constants ) i : integer; 
CONST menuNum : Integer; 
№11 = °7; TheMenuHdle : MenuHandle; 
AppleMenuID = 1; itemNum : Integer; 
FileMenuID = 2; NemeHolder : str255; 
EditMenuID = 3; dummy : Integer; 
MIDIMenuID = 4; ignore : boolean; 
AboutID - 200; TheValue : longint; 
( Global Variables ) 
VAR BEGIN 
myMenus : ARRAY([AppleMenuID. .MIDIMenuID] OF MenuHandle; IF codeWord © 0 THEN ( nothing wes selected) 
Done : Boolean; ( true when user selects quit) BEGIN 
(This is a way to do the about box so that it doesn’t inter- menuNum := HiWord(codeWord); 
fere with the application. For instance, you can make menu itemNum := LoWord(codeWord); 
selections while the about box is visible.) CASE menuNum OF ( the different menus} 
AppleMenuID : 
PROCEDURE ShowAbout; BEGIN 
VAR IF itemNum « 3 THEN 
theDlog : DialogPtr; BEGIN 
oldPort : GrafPtr; ShowAbout; 
BEGIN END 
GetPortColdPort); ELSE 
theDlog := GetNewDialogCAboutID, NIL, Pointer(C- 122; BEGIN 
SetPortCtheD109); GetItemCnyMenus[AppleMenuID], 
DrewDialog(theD10g); itemNum, NameHolder ); 
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dummy := OpenDeskAccCNemeHo der); 
END; 
END; 
FileMenuID : 
BEGIN 
CASE ItemNum ОҒ 
| 


BEGIN 
DoXfer; 
END; 


BEGIN 
Done := true; 
END; 
END; 
END; 
EditMenuID : 
BEGIN 
ignore := SystemEditCitemNum - 1); 
END; 
MIDIMenuID : 
BEGIN 
TheMenuHdle := GetMHandle(4); 
FOR i := 1705 DO 
CheckItemCTheMenuHdle, i, false); 
MIDIThruAC0); 
MIDIThruBC0); 
CASE ItemNum OF 
1 . 


BEGIN 


CheckItemCTheMenuHdle, 1, true); 


MIDIThruACD; 
END; 


BEGIN 


CheckItemCTheMenuHdle, 2, true); 


MIDI ThruAC2); 
END; 


BEGIN 


CheckItemCTheMenuHdle, 3, true); 


MIDIThruB( 1); 
END; 


BEGIN 


CheckItemCTheMenuHdle, 4, true); 


MIDIThruBC2); 
END; 


 BEGI 


MIDIThruACO); 
MIDIThruBC0); 
END; 
END; 
END; 

END; 

HiliteMenuC2); 

END; 

END; 


PROCEDURE DealWithMouseDowns CtheEvent : EventRecord); 
VAR 


location : Integer; 
windowPointedTo : WindowPtr; 
mouseLoc : point; 
windowLoc : integer; 
VendH : Longint; 
Height : Integer; 
Width : Integer; 
BEGIN 
mouseLoc := theEvent .where; 
windowLoc := FindWindow(mouseloc, windowPointedTo); 
CASE windowLoc OF 
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N 
CheckItemCTheMenuHdle, 5, true); 


inMenuBer : 
BEGIN 
ProcessMenu(MenuSe lect(mouseLoc)); 
END; 
inSysWindow : 
BEGIN 
SystemClickCtheEvent, windowPointedTo); 


END; 
OTHERWISE 

BEGIN 

END; 


PROCEDURE DealWithKeyDowns CtheEvent : EventRecord); 
TYPE 


Trick = PACKED RECORD 
CASE boolean OF 
true : € 
long : Longint 


false : ( 
chr3, chr2, chri, chrÜ : char 
) 
END; 
VAR 
CharCode : char; 
TrickVar : Trick; 
BEGIN 
TrickVar.long := theEvent.message; 
CharCode := ТгіскУаг.сһг0; 
IF BitAnd(theEvent modifiers, CmdKey) = CmdKey THEN 
(check for a menu selection) 
BEGIN 
ProcessMenuCMenuKeyCCharCode 2); 
END 
END; 


PROCEDURE Ma inEventLoop; 
VAR 


Event : EventRecord; 
ProcessIt : boolean; 
x : byte; 
TheValue : Longint; 
BEGIN 
REPEAT 
Sys temTask ; 
ProcessIt := GetNextEventCeveryEvent, Event); 
( get the next event in queue) 
IF ProcessIt THEN 
BEGIN 
CASE Event .what OF 
mouseDown : 
DealWi thMouseDowns(Event); 
AutoKey : 
DealWithKeyDowns(Event); 
KeyDown : 
DealWithKeyDowns(Event); 
OTHERWISE 
BEGIN 
END; 
END; 
END; 
UNTIL Done; 
END; 


PROCEDURE MakeMenus; 
VAR 


index : Integer; 
TheMenuHdle : MenuHandle; 
BEGIN 
FOR index := AppleMenuID TO MIDIMenuID DO 
BEGIN 
nyMenus[ index] := GetMenuC index); 
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( get the menus & display them) 


InsertMenu(myMenus[ index], 0); 
END; 
AddResMenu(CmyMenus [AppleMenuID], ‘DRVR’); 
DrewMenuBer ; 

(put а check mark on the “none” menu item by default) 
TheMenuHdle := GetMHandle(4); 

CheckItemCTheMenuHdle, 5, true); 

END; 


( Program Starts Here ) 

BEGIN 
Done := false; 
FlushEventsCeveryEvent, 0); 


InitSCCA; 

Ini tSCCB; 

InitTimer(782 * 5); 

(increment the counter every 5 milliseconds} 
Star tCounter; 


MakeMenus; 
InitCursor; 
MainEventLoop; 


ResetSCCA; 
ResetSCCB; 
QuitTimer; 


END. 


UNIT LSPMIDI; 
(Midi library available on this source code disk for LSP } 
INTERFACE 

PROCEDURE InitSCCA; 

(call this once at the beginning of your application if you 
are going to use the modem port for MIDI) 


PROCEDURE TxMIDIA CTheData : integer); 

(use this procedure to transmit a byte of MIDI data through 
the леді port the MIDI byte is in the lower 8 bits of the 
word 


FUNCTION RxMIDIA : LongInt; 

(use this function to get a byte of MIDI data end the 
counter value associated with that byte through the modem port 
the MIDI byte is in the lower 8 bits of the longword the upper 
3 bytes of the longword contain the counter value when the 
byte arrived at the Macintosh) 


PROCEDURE MIDIThruA CThrucode : integer); 
(this is for the MIDI thru function) 

(the Thrucode variable is as follows:) 

(2 = no MIDIThru function) 

(1 = MIDIThru on the same channel) 

(2 = MIDIThru on the opposite channel) 


PROCEDURE ResetSCCA; 

(call this procedure when your application is done if you 
called InitSCCA at the beginning of your application or the 
system will crash) 


PROCEDURE InitSCCB; 
(call this once at the beginning of your application if you 
аге going to use the printer port for MIDI) 


PROCEDURE TxMIDIB (TheData : integer); 

(use this procedure to trensmit & byte of MIDI date through 
the printer port the MIDI byte is in the lower 8 bits of the 
word 


FUNCTION RxMIDIB : LongInt; 


(use this function to get а byte of MIDI data end the 
counter value associated with that byte through the printer 
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port the MIDI byte is in the lower 8 bits of the longword the 
upper 3 bytes of the longword contain the counter value when 
the byte arrived at the Macintosh) 


PROCEDURE MIDIThruB (Thrucode : integer); 
(this is for the MIDI thru function) 

(the Thrucode verieble is es follows:) 

(0 = no MIDIThru function) 

(1 = MIDIThru on the seme channel) 

(2 = MIDIThru on the opposite chennel) 


PROCEDURE ResetSCCB; 

(call this procedure when your application is done if you 
called InitSCCB at the beginning of your application or the 
system will crash) 


PROCEDURE InitTimer (TimrValue : integer); 

(call this procedure once at the beginning of your applica- 
tion if you are going to make use of time-stamping. 1 
millisecond = decima! 782) 


PROCEDURE LoadTimer (TimrValue : integer); 

{call this procedure if you want to change the interval of 
ШЫ that the counter is incremented. 1 millisecond = decimal 
782 


PROCEDURE Star tCounter; 
(call this procedure to set the counter value to 1) 


FUNCTION GetCounter : LongInt; 
(call this function to get the current value of the 
counter) 


PROCEDURE QuitTimer; 

(call this procedure when your application is done if you 
called InitTimer at the beginning of your application or the 
system will cresh) 


IMPLEMENTATION 
(А 


PROCEDURE InitSCCA; 
external; 

PROCEDURE TxMIDIA; 
external; 

FUNCTION RxMIDIA; 
external; 

PROCEDURE MIDIThruA; 
external; 

PROCEDURE ResetSCCA; 
external; 

PROCEDURE InitSCCB; 
external; 

PROCEDURE TxMIDIB; 
external; 

FUNCTION RxMIDIB; 
external; 

PROCEDURE MIDIThruB; 
external; 

PROCEDURE ResetSCCB; 
external; 

PROCEDURE InitTimer; 
external; 

PROCEDURE LoedT imer ; 
external; 

PROCEDURE StartCounter; 
external; 

FUNCTION GetCounter ; 
external; 

PROCEDURE QuitTimer; 
external; 


($h-) _ 
END. Sol 
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ABC's of C 
Peeking at Heap Zones 


Memory is the stuff of which there never is enough. To 
reduce problems due to lack of memory, most languages provide 
means to grab some memory for use and later release it. Standard 
C has a number of functions to manage memory allocation and 
deallocation. We are not going to discuss these in any detail 
because the Macintosh has a complete memory management 
system. We have been using the memory management routines 
indirectly every time we opened a window, but as we go further 
into Mac programming we need to manipulate memory directly. 


Macintosh Memory Organization 
Just about every book on programming the Macintosh has 
pictures of the Macintosh memory map. For the 64K ROMS, it 
looks roughly like: 


Main Screen Buffer 


Application Globals 


Application Heap 


Trap Vectors 


Fig. 2 Memory Map 


I left off the physical addresses because they are typically 
not important, and because many of them can change as a 
function of memory size. For the 128K ROMS, the arrangement 
is slightly different. The ROM trap dispatch table has been 
expanded and is now in two sections, with the second section 
between the system heap and the second system globals area. 

For this discussion, the most important areas are the Appli- 
cation Heap and the Stack. The stack is where all C parameters 
and local variables reside (actually, this depends on the compiler. 
Some compilers will pass some parameters in registers, and 
programmers may specify variables to be register variables, and 
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Ман Zone 
Zone Info 
Neu Handle 
Меш Pointer 
Free Handle 
Free Pointer 


blocks 32 free 8 relocatable 21 non-relocatable 3 


Figure 1: Examining the heap 


if a register is available, the variable will be placed in a register). 
The stack grows and shrinks with the function calls and returns. 
The application heap is the area where memory is explictly 
reserved and released. Unlike the stack, memory reserved in the 
heap does not disappear when a function returns. This allows the 
creation of large, complex data structures "on the fly." 


C Memory Allocation 
Since C is used on systems other than the Mac (really, there 
are other computers!), you might want to know about the stan- 
dard C memory functions. 


malloc() allocates some memory. It receives one parameter, the 
number of bytes to allocate, and returns a pointer to the 
region of memory. 

free() деаПосаіеѕ memory previously allocated. It receives 

one parameter, a pointer previously returned by mal- 

locQ. 


The actual names and implementation will vary somewhat 
by compiler. Lightspeed C provides eight allocation functions 
and five deallocation functions in its standard library. Most of 
these are there to provide compatibility with Unix. The other 
Macintosh C compilers with which I am familiar also provide the 
standard C functions. 

Unless you are using your Mac to develop software to run 
on another system, it is not a good idea to use the standard C 
memory functions. The primary reason for this is that on the Mac 
there are two kinds of allocated memory, relocatable and non- 
relocatable. None of the C compilers I have seen make any 
attempt to relate the standard C memory functions to the Mac 
memory functions (I assume the standard C functions retum 
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pointers to non-relocatable blocks of memory, but this is not 
made apparent). 


Macintosh Memory Allocation 

Again, since information about the Mac memory manage- 
ment system is readily available, I am not going to attempt to 
cover all the details here. There are, however, several key 
concepts which probably deserve some attention. 

As mentioned above, memory comes in two kinds, relocat- 
able and nonrelocatable. A relocatable block may be moved 
around in the heap by the operating system to make room for 
additional allocations. Since it may be moved, you do not receive 
a pointer to the block but a handle that points to a master pointer 
that points to the block. 

Since the master pointer does not move (it is nonrelocat- 
able), the value of the handle remains constant. When you 
request a nonrelocatable block, you receive a pointer directly to 
the block since the operating system will not move it. In general 
it seems that relocatable blocks are preferred since the operating 
system can move them out of the way when needed. If there are 
many nonrelocatable blocks, the operating system may not be 
able to satisfy a memory request because there may be no single 


Handle 


Master Pointer 


Pointer 


Fig. 3 Handles and Pointers 


space available big enough to meet the need. Without the ability 
to move blocks in the heap around (compact the heap), you will 
run out of memory sooner. 

One problem with relocatable blocks is that it takes two 
pointers to access the data. One can always obtain a pointer to the 
block, but the system may move the block while you are using it. 
This situation, known as a dangling pointer, can cause quite 
exciting and hard to diagnose problems. If you need to use a 
particular block alot in a function, you may lock the block which 
makes it temporarily nonrelocatable. Be sure to unlock it when 
you are done. 

Another option for relocatable blocks is to purge them from 
memory. The operating system will do this if it needs more 
memory than is available, but only if you have marked a block as 
purgeable. New relocatable blocks start out as not purgeable. 
Note that if a block is purged, you will still have the handle, but 
the pointer it contains will be set to zero. To reuse the block, it 
is necessary to reallocate the block and rebuild the data. There is 
a function that reallocates purged blocks; the data is the 
programmer's responsibility. 

Memory management errors are available through the func- 
tion MemError(). A value of zero (NoErr) means there was no 
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error; negative values represent error codes. 


printw 
There were a few changes to printw. We have added the 
ability to print rectangle and point coordinates. This is useful 
when using graphics. This time I added hex output. It is also now 
a seperate file. I have found it useful, but we probably won't print 
the whole thing again after this month, since this is the second 
time we've seen this routine. 


The Program 

Our program this month makes a number of trap calls that 
deal with memory management. From these calls, we can display 
information about the application heap and see how the creation 
of handles and pointers affects the available heap space. To keep 
things simple, we have created a very minimal Mac program that 
just puts up a blank window. The real heart of the program is the 
memory functions menu that lets us create handles and pointers 
and free them so we can see the effect on the heap. Fig. 1 shows 
how we print the memory information in our debugging print 
window using the printw() routine we learned about in a previous 
issue of MacTutor. 

When yourun the program, use the Zone Info menu item to 
see the state of the heap. I left the abc window in (under the File 
menu). Make a window and then run Zone Info. The Show Zone 
item traces through the zone and gives a line of information about 
each block, telling if itis free, relocatable or non-relocatable. By 
the way, the information needed to trace through the heap is not 
ordinarily available so there is a structure defined just before 
main() that defines the information needed to understand the 
heap. This structure, called memheads, is actually the defini- 
tion of a block header. The other menu items create handles and 
pointers using NewHandle and NewPtr, and then if the handle or 
pointer is valid, another menu item lets us dispose of those 
handles and pointers, using DisposHandle and DisposPtr. The 
Zone Info menu item should show the effect of each of these 
operations on the available space in the heap. 

There is another "feature" to this program. Every time you 
reserve a relocatable block, the size reserved doubles. With zone 
info, you can watch the memory manager increase the size of the 
heap and eventually run out of memory. 

The key to the program is the GetZone trap call. This returns 
a pointer to the current heap zone. Once we have this pointer, our 
ShowZone and CountZone routines will read and print infor- 
mation about the zone for us. See the domem(item) routine іп 
the listing to see where this trail starts with the memory menu 
item. 

The term zone is how the heap is divided. Each zone in the 
heap is divided into blocks. A block is an even number of bytes, 
the minimum of which is 12. When your application starts up, call 
MaxApplZone to expand the application heap zone to its limit. 
Normally, an application would only be concerned with a single 
heap zone for itself, but you can create additional zones in the 
heap. One of our menu items does call MaxApplZone so you can 
see if it has any effect depending on when you call it. We can find 


© The Essential MacTutor, Vol. 3 


out the free space left in a heap zone by calling FreeMem. 

Once we get a pointer to the current heap zone, then we can 
examine the zone. А heap zone contains a 52 byte zone header, 
the allocated blocks within the zone, and a final minimum size 
block at the end of the zone called the zone trailer. The zone 
header is a pascal record defined below: 


Zone = RECORD 


bkL im: Ptr; (zone trailer block) 

purgePtr : Ptr; (used internally) 

hFstFree: Ptr; (first free master pointer) 

zcbFree: LONGINT; (number of free bytes) 

gzProc: ProcPtr; (grow zone function) 

moreMast: Integer; {master pointers to 
allocate) 

flags: Integer; (used internally) 

cntRel: Integer; (not used) 

maxRel: Integer; (not used) 

cntNRel : Integer; (not used) 

maxNRel : Integer; (not used) 

cntEmpty: Integer; (not used) 

cntHandles: ^ Integer; (not used) 

minCBFree:LONGINT; (not used) 


(purge warning proc) 
(used internally) 
(used internally) 
(first usable byte in zone) 


purgeProc:ProcPtr; 

sparePtr : Ptr; 

allocPtr: Ptr; 

heapData: Integer 
END; 


The zone pointer is defined to be of type THz, which is 
simply declared to be ‘Zone. HeapData is the first two bytes in 
the block header of the first block in the zone. Hence to find the 
first usable block, we can say (9 (myZone^.heapData), which is 
a pointer to the first block header. Or in c, we would use &zone- 
>heapData. The block header is 8 bytes: the tag byte, a three byte 
block size, and a four byte identifier that indicates whether the 
block is relocatable, non-relocatable or free. The four byte 
identifier is actually a handle, pointer or unused depending on the 
nature of the block. The tag byte also contains information on the 
nature of the block in bits 6 and 7. We can examine the nature of 
every block in the heap zone by adding the block size to the 
address of the first block and going from block to block checking 
the two high order bits of the tag byte. All of this is discussed in 
great detail in the IM chapter on the memory manager. This is 
implemented in our program in the showzone(zone) routine. 
Our memhead structure actually combines the tag byte and block 
size into a single four byte field called physsize. The second four 
bytes in the block header are stored in our memhead structure in 
the relhand field. We decode the physsize field to obtain the tag 
byte, and the block size, then we break down the tag byte to obtain 
the block status, and the size correction. All of this is done in the 
showhead(head) routine. Study carefully the three routines 
showhead, showzone and countzone to see how the block 
headers are decoded and the block size, status and address are 
then printed in our print window. 


Final Comments 
Using the techniques shown in this program, you can 


construct your own heapshow utility or TMON heap display. A . 


good discussion of how TMON examines and displays the heap, 
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is available in Dan Weston's new book, Macintosh Assembly 
Language Programming, Vol. II. There are some useful memory 
management functions not included this month such as Моге- 
Masters() which reserves space for master pointers needed by 
NewHandle(). These should be easy to include in the program if 
you need to get an idea of how they work. 

Next time we'll return to quickdraw and try to draw poly- 
gons, regions, and pictures. 


é Fite Edit ПШ 


Ман Zone 
Zone info 

New Hendie 
New Pointer 
Free Handle 
Free Pointer 


address 67798 size correction O free block physical size 19038 
address 86836 size correction 4 rel physical size 12 

address 86846 size correction O rel physical size 182 
address 87030 size correction O free block physical size 4670 
address 91900 size correction O free block physical size 1973560 
blocks 54 free 21 relocetable 30 non-relocatable 5 


Figure 4: ShowZone gives a heap dump 


/* вев.с 

* explore memory allocation 
x LS C by Bob Gordon 
*/ 

#include "абс.һ" 
include "MemoryMgr .h" 
"include "Quickdrew.h" 
"include "EventMgr .h" 
"include "WindowMgr .h" 
include  "MenuMgr.h" 
include "FontMgr.h" 


/* defines for menu ID's */ 


def ine Mdesk 100 
tdef ine Mfile 101 
#def ine Medit 102 
def ine Mmem 183 
/* File */ 

def ine iNew 1 
ttdef ine iClose 2 
def ine iQuit 3 
/* Edit */ 

“def ine iUndo 1 
def ine iCut 3 
"def ine iCopy 4 
def ine iPeste 5 
/* Menory */ 

#def ine iZone 1 
&def ine iMzone 2 
def ine iInfo 3 
def ine iHand 4 
“def ine iPtr 5 
def ine iFreeH 6 
"def ine iFreeP 1 


/* Global vartables */ 


MenuHendle 
MenuHandle 


menuDesk;  /* menu handles */ 


menuF ile; 
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MenuHandle nenuEdit; 
MenuHandle menuMem ; 
WindowPtr theW indow; 
WindowRecord windowRec; 
Rect dragbound; 
Rect limitRect; 
/* 


* structure needed to examine heap not typically 

* supplied by Mac development systems because normal 
* applications do not need to examine the heep. 

*/ 

те menheades 


long physsize; 
long relhand; 
; 
ты: 


іпі(5,5 00; /* sys init */ 
initapp(); /* appl init */ 
eventloop(); 


/* system initialization */ 
Шы 


Init6raf (&thePort); 

InitFontsC); 

InitWindowsC); 

InitCursor(); 

InitMenusC); 

theWindow = Nil; /* no window */ 

SetRect(&dragbound, 8,0,512,250); 
SetRect(&l imi tRect, 60, 40,508, 244); 


/* 
Ж application initialization 


* Sets up menus. */ 
ыы 


setupmenu( ); 


/* 
ж set up application's menus 
x Each menu is а seperate group 
Ж of lines. 
*/ 
мр 


menuDesk = NewMenu(Mdesk, CtoPstr("\24")); 
AddResMenu (menuDesk, ‘DRVR'); 
InsertMenu (menuDesk, 0); 


menuFile = NewMenu(Mfile, CtoPstr("File")); 
AppendMenu (menuF ile, 

CtoPstrC"New/N; Close;Quit/Q"2); 
InsertMenu (menuFile, 0); 


menuEdit = NewMenuCMedit, CtoPstrC"Edit"22; 
AppendMenu (menuEdit, 


CtoPstrC" CUndo/Z; C7; (Cut /X; CCopy/C; (Paste/V; (Clear")); 


InsertMenu (menuEdit, 0); 


menuMem = NewMenu(Mmem, CtoPstrC"Memory" 2); 
AppendMenu (menuMem, 
CtoPstr("Show Zone;Max Zone;Zone Info;New Handle;New 
Pointer")); 
AppendMenu (menuMem,CtoPstrC"Free Handle;Free Pointer")); 
InsertMenu (menuMem, 0); 
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DrawMenuBar C2; 


/* Event Loop 


* Loop forever until Quit 
x 
па 

EventRecord theEvent; 
char С. 
short windowcode; 
WindowPtr ww; 
whi leC True) 


if CtheWindow) /* this code is here to */ 
/* prevent 
closing an */ 
EnableItem(menuFile,2); /* already closed window */ 
DisebleItemCmenuF ile, 1); 


else 


EnableI tem(menuF ile, 1); 
бағыта 


if (GetNextEventCeveryEvent, &theEvent)) 


SwitchCtheEvent . what) 
( /* only check mouse */ 
case mouseDown: 
domousedown(&theEvent); 
break; 
default: 
break; 


) 


/* domousedown 

x handle mouse down events 
*/ 

domousedown(Cer ) 

( EventRecord žer; 


short windowcode ; 
WindowPtr whichWindow; 
short ingo; 

long size; 

long newsize; 
RgnPtr rp; 

Rect box; 

Rect *boxp; 


windowcode = FindWindowCer-?where, &whichWindow); 
Switch Cwindowcode ) 


case inDesk: 
if nee notequal 9) 


HiliteWindowCtheWindow, False); 
DrawGrowIconCtheW indow); 


break; 

case inMenuBar : 
domenu(MenuSe lectCer-? where )); 
break; 


) 


/* domenu 
x handles menu activity 
x simply а dispatcher for each 
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x menu. 
*/ 
domenuCac) 
Tong mc; /* menu result */ 
short menuld; 
short menuitem; 


menuId = HiWord(mc); 
menuitem = LoWord(mc); 


switch Cmenuld) 


case Mdesk : break; /* not handling DA's */ 
case Mfile : dofileCmenuitem); 


break; 
case Mmem : domem(menuitem); 
) break; 
HiliteMenuC0); 
) 
domenCiten) 
short item; 
THz zone; 
stetic long size = 1024; 
stetic Handle hand = 0; 


static Ptr ptr = 0; 
struct memheads*memhead; 


switch Citem) 


case iZone : 
zone = GetZone(); 
printwC"\nzone #14 ",zone); 
showzone (zone); 
break; 
case iMzone : 
MaxApp 1Zone(); 
break; 
case iInfo : 
zone = GetZone(); 
countzone(zone ); 
break; 
case iHand : 
hand = NewHandle(size); 
printwC"\nhandle Z1d pointer $1x error %d 
" папа, *hand, MemError()); 
printwC" free mem #10 ",FreeMem()); 
size = size * 2; 
break; 
case iPtr : 
ptr = NewPtr(size); 
printwC"\npointer &1а error %d free mem 
%1d",ptr,MemError(),FreeMem()); 
showhead(ptr-8 ); 
break ; 
case iFreeH : 
if Chand equals 0) 
printw("\nNo current handle to free"); 


else 
DisposHendleChand); 
hand = £; 

break ; 


case iFreeP : 
if (ptr equals 0) 
printwC"\nNo current pointer to free"); 


else 
DisposPtr (ptr); 
ptr = 0; 
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) 


showheadChead) 


struct memheads*head; 
uchar tagbyte; 


printw ("\naddress #14 ",(char* head + 8); 
tagbyte = head-»physsize ›› 24; 

printw ("size correction Sd ",tagbyte & xF), 
tagbyte ››= 6; 

rd Ctegbyte) 


case 0: 
printwC" free block "2; 
breek; 

cese 1: 
printwC" non rel "3; 
breek; 

сазе 2: 
printwC" rel "2; 
break; 


printwC" physical size #14 “,head-»physsize & OxODFFFFFF); 
return Ctagbyte); 


showzone(Czone ) 


( 


THz zone; 


struct memheads*memhead; 


short tblocks = 0; 
short tfree = 0; 
short ігі = 0; 

short tnonrel = 8; 


memhead = (struct memheads* &zone-> heapData; 
while Cmemhead < (struct memheads*)zone-> БК im) 


d CshowheadCmemhead)) 


cese Ø : tfreet+; break; 
case 1: tnonrel++; break; 
case 2 :  trel**; break; 


tblocks**; 
memhead = (struct memheads*)((char* memhead + (memhead- 


»physsize & OxBOFFFFFF)); 


printwC"An blocks Sd free Sd relocatable %d non-relocatable 


tblocks, tfree, trel, tnonrel); 


) 

countzone(zone) 

THz zone; 
struct memheads*memhead; 
short tblocks = 9; 
short tfree = 0; 
short trel = 0; 
short tnonrel = 9; 
uchar tagbyte; 


memhead = (struct memheads* )&zone-> heapData; 
МУ (nemhead < (struct memheads*)zone-?bkL im) 


tagbyte = memhead->physsize ›› 24; 
tegbyte ››= 6; 
ши Ctagbyte) 


case 0 : tfreet+; break; 
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case 1: tnonreltt; break; 
case 2:  treltt; break; 


tblockst+; 
memhead = (struct memheads*)((char* )memhead + (memhead- 
es % 0х00ҒҒҒҒҒЕ)); 


printwC"An blocks Sd free Sd relocatable $d non-relocatable 
d ЭА 


tblocks, tfree, trel, tnonrel); 


) 


/* dof ile 
x handles file menu 
x/ 
dof ileCiten) 
short item; 


char *titlel; /* first title for window */ 
Rect boundsRect; 


switch Citem) 


case iNew : /* open the window */ 

titlel = "ABC Window"; 

SetRect(&boundsRect, 50,50, 400,200); 

theWindow = NewWindow(&windowRec, &boundsRect, 
CtoPstr(title1), True, documentProc, 
CWindowPtr) -1, True, 0); 

DrewGrowIconCtheWindow); 

PtoCstrCtitle1); 

DisableItemCnenuF ile, 1); 

EnebleItemCmenuF i 1e,2); 

break ; 


case iClose : /* close the window */ 
CloseW indow( theW indow); 
theWindow = Nil; 
DisableI temCmenuF ile,2); 
EnebleItemCmenuF ile, 1); 
break; 


case iQuit : /* Quit */ 
ExitToShe11C); 
break; 


8include  "abc.h" 
8include "Quickdrew.h" 
8$include "EventMgr .h" 
include "WindowMgr .h" 
8include  "MenuMgr .h" 
"include "FontMgr .h" 


/* printwC) 
x 


* Displays strings and numbers in a 
* special window 


This function is designed to receive 

а variable number of parameters. The 
number is computed by the number of 
percent signs in the contro] string. 

If the number of parameters following the 
control string does not match the 

number of percent signs, expect 

the unexpected. 


$** 9€ 9€ и и и и и и 


123 
— 


printw(cs) 
| char *с$; /* the control string */ 


"defineBufsz 14 /* size of buffer to hold */ 
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/* converted numbers */ 


static Rect boundsRect; /% variables for */ 
static Rect windowRect; /% defining printw */ 
static WindowRecord wrc; /* window, pw is */ 
Static WindowPtr pw = 0; /* initialized to Ø */ 
static short linesz; /* size of line */ 
WindowPtr oldport; /% save grafport here */ 
FontInfo info; 

short nl; 

Point pt; 

RgnHendle updrgn; /* needed for scrolling */ 
char numAsStr[Bufsz]; /* number conversion */ 
short nsz; * size of numbers (2 or 4) */ 
char **ts; /* ptr to ptr to ctr] string */ 
char *ps; /* ptr to parameters */ 

ulong num; * for number conversion */ 
short convcher;  /* found conversion char */ 
short islong; /* number is a long */ 

short ishex; /* display in hex digits */ 
Short isp; /* pescal string or point */ 
short isr; /* rectangle */ 

Point *ptp; 

Point ***ytp; 

Point *xtp; 

Rect «гір; 

сһаг с; /* cher peremeter */ 

cher %5; /* string pointer paremeter */ 
long tcs; 

char *tps; 


/* Window rectancgle coordinates */ 


def ine w] 

def ine wr 512 
8def ine wt 250 
8def ine wb 342 


GetPort(&oldport); /* save current graph port */ 
if (pw equals 0) /* if window does not exist, */ 


/* open it */ 
SetRectC&boundsRect , w1, wt, wr, wb); 
pw = NewWindow(&wrc, &boundsRect, 
CtoPstrC""), True, plainDBox, 
(WindowPtr) -1, True, 0); 
GetFontInfo(&info); ^ /* compute line height */ 
linesz = info.ascent + info.descent; 
nl = linesz; /* move down one line as */ 


/* writing will be above */ 


else 


/* boundary. No need to */ 
nl = 0; /* move line if already open */ 


SetPort(pw); /% Set graf port to this window */ 
Move(0,n1); /* Move (relative) */ 


ts = &cs; /* get address of control string ptr */ 
ps = (char *)ts;  /* convert to pointer to params */ 
ps += sizeof (long); /* skip over control string ptr */ 
ics = Clong)cs; 
tps = ps; 
while (*cs) /* loop until end of control string */ 

( 

ixl (*cs) /* check each character */ 

case ‘%' : /* percent sign: check conversion */ 
с5++; /* point to next char */ 


сопусһаг = False; /* init for conv loop */ 
islong = False; 

ishex = False; 

isp = False; 

isr = False; 

do ( /* loop until reach conversion cher */ 
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switch (*cs) 
( 


case ']l' : 
islong = True; 
cstt; 
break; 

cese 'r' : 
isr = True; 
cs*t*; 
break; 

case 'p' : 
isp = True; 
cstt; 
break; 

case 'u' 

case 'd' : 
if y d 


/* indicates a long */ 


/* unsigned decimal */ 
/* signed decimal */ 
/* extract number */ 


num = *Culong*)ps; 
nsz = sizeofClong); 
else 
num = *Cushort*)ps; 
nsz = sizeof (short); 
) 
ps += nsz; /* next param */ 


ntoaCnum,nsz,'u' - *cs,numAsStr); 
DrawStr ing(CtoPstrCnumAsStr 22; 
convchar = True; 
break; 
case 'x' : 
if X ali /* extract number */ 
num = *Culong*)ps; 
592 = sizeof(Clong); 


else 


num = *Cushor t*)ps; 
nsz = sizeof(short); 


ntoxCnum,nsz,numAsstr ); 
DrawStr ing(CtoPstr CnumAsStr )); 
convcher = True; 
ps += nsz; /* next param */ 
break; 

case 'S' 

S = *(char **)ps; 

if Cisp) 
DrewStr ingCs?; 

else 


DrawStr ingCCtoPstrCs2); 
PtoCstr(s); 


ps += sizeof Cchar*); 


convchar = True; 
break; 

case 't' : 
if Pus 


ptp = *(Point **)ps; /*111*/ 
DrewString C"\pPoint h: "2; 
ntoaCCulong)ptp-?h,2, True, numAsStr); 
DrawStr ingCCtoPstr(numAsStr2); 
DrawString С"\р v: "5; 
ntoaCCulong)ptp-?v,2, True,numAsStr?); 
DrawStr ingCCtoPstr(numAsStr2); 


ia (isr) 


rtp = *(Rect**)ps; 
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DrawString C"MpRect t: "); 
ntoaCCulong rtp-> top, 2, True, numAsStr ); 
DrawStr ing(CtoPstrCnumAsStr 22; 
. DrawStringC"\p 1: "2; 
ntoaCCulong)rtp-? lef t,2, True, numAsStr); 
DrawStr ing(CtoPstrCnumAsStr 22; 
DrawStringC"\p b: "2; 
ntoaCCulong2rtp-?bottom,2, True, numAsStr); 
DrawStr ing(CtoPstrCnumAsStr 2); 
DrawStringC"\p г: "2; 
ntoaCCulong or tp—> right, 2, True,numAsStr); 
ына аа 


ps += sizeofCchar*); 
convchar = True; 
break; 


cese “с” 
с = *(ushort*)ps; 
DrawChar(c); 
nsz = sizeof(short); 
convchar = True; 


ps += NSZ; 
break; 
default : /* if not expected char, */ 


DrawChar(*cs); /* write char out */ 
convcher = True; 


) while (пої сопусһаг); 
break ; 
case '\п' :/* newline С'\п') in control string */ 
GetPen(&pt); — /* find current pen position */ 
if (pt.vtlinesz > wb-wt) 
/* if it goes off window, */ 


/* scroll the window */ 

updrgn = NewRgn(); 
ScrollRectC&Cpw-?portRect2,2, -linesz,updrgn?; 

DisposeRgnCupdrgn?;  /* no update */ 

қаны /* move onto window */ 


Move(-pt.h, linesz); /* move to next line */ 
break; 

default : /* any other character just gets */ 
DrawChar(*cs); /* written on the window */ 


cstt; /* move pointer to next char */ 
/* in control string and continue */ 


SetPortColdport); /* restore orignal graf port */ 
/* Convert numbers to ascii strings 
x Handles signed and unsigned 
* short and long values 
* Note: Length of string returned 
x must be large enough to 
x hold -26 (12 bytes) 
x/ 
ntoa(n, len, issigned,s) 
ulong n; /* number to convert */ 
short len; /* size of n (2 or 4)*/ 
short issigned; /* signed flag (True = Signed) */ 
char *s; /* string to return */ 
char (61121; /* temporary string */ 
int i = 0; /* counter, initialized */ 
ulong n; /* working copy of */ 
long Sn; /* to convert signed values */ 
if (n equals 0) /* if n is zero, place '@' */ 
ts[it*t] = '0'; /* in temporery string */ 
else 
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do 
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( 
if Cissigned) /* if sign flag is set, */ 
/* convert to signed value */ 
if Clen equals sizeofClong)) 
sm = (long); 
else 
sm = Cshort)n; 
if Cissigned = sm < 0) /* Check if value is */ 


n = -SM; /* negative. If so, */ 
/* keep the flag and */ 
/* get the absolute value */ 
while (n) /* Convert number into ascii */ 
( /* by repeatedly taking mod */ 


ts(it*t1 =n% 10 + '0'; /* and dividing. 

n /= 10; /* gives а string in */ 
/* reverse order */ 

/* If number wes negative, */ 
/* stick а minus sign in */ 
/* the string.*/ 


This */ 


if Cissigned) 
ts(it*t] = '-'; 


/* Reverse the string */ 


*st*t = ts[--1); /* to the correct direction*/ 


) 
while (1); 
*8 = '\0'; 


/* Place null terminator on */ 
/* string */ 


/* Convert numbers to hex strings 
x Handles unsigned 
x short end long values 
* Note: Length of string returned 
x must be large enough to 
x hold 46 (12 bytes) 
%/ 
ntox(n, len,s) 
ulong n; /* number to convert */ 
short len; /* size of n (2 or 4)*/ 
char Xs} /* string to return */ 


/* counter, initialized */ 
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Visual Programming 
C The Easy Way with VIP! 


Getting started 

While thinking abouthow bestto present information useful 
te new Mac programmers, I recalled some of my own frustrations 
in trying to learn Macintosh programming. Before V.I.P., there 
seemed to be at least two hurdles to achieving even a modest 
success in programming on the Macintosh. First was the requi- 
site learning of the chosen language's rules and syntax, and then 
trying to fathom the complexities of dealing with the Mac 
toolbox specifics. What I wanted was a simple example program 
that featured all of the fundamental aspects of nearly every Mac 
program, i.e. Menus, Windows, Dialogs, and Events. The 
example I longed for had to be simple, logical, and easily 
modified for my own purposes. Well, to make a long story short, 
I never was able to jump both hurdles - until V.I.P. 

Our introductory course in Visual Interactive Programming 
will attempt to lower the hurdles by providing a simple Macin- 
tosh program featuring all of the attributes mentioned above. 
Along the way we will experience the advantages of modularity, 
create menus and implement actions accordingly. Display and 
draw in a couple of types of windows. Learn about local and 
global objects, argument passing between routines, and hope- 
fully have some fun too. VIP is truly an amazing new approach 
to Mac programming that is as fun and straight forward as MPW 
and MacApp are laborious and complex. And as we will see, 
creating C source code from VIP is really having your cake and 
eating it too! 

The program presented here is a completely functional 
Macintosh program, although it is a little brain damaged, and 
really doesn't do much yet. It does provide a text edit window for 
displaying a file's contents and allows the file contents to be 
printed. Readers familar with our text edit shell program in the 
January issue will recall that those functions can generate a 
considerable amount of source code in "normal" languages. 
Moreover, with minor changes, this program can serve as a shell 
for mostany application you wish to create. In a future article we 
will add the guts and feathers routines which perform the 
program's peculiar actions. 


Routines have Relations 

Before we begin, take a look at figure 1. This relations tree 
is created automatically by V.I.P. and graphically displays the 
relations of each routine making up our example program. А 
routine, as you may recall, is simply a logical grouping of V.I.P. 
procedures and logic forms which perform actions as specified 
by the programmer. Routines are called by other routines, or may 
even be called by themselves to control the execution sequence, 
or perform specific tasks. In other languages, a subroutine or 
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6 File Edit Routines Special Run 


Mouse Click Programming with VIP! 


procedure, but in VIP, there are no return statements to w 
about. 


Program flow 

Main calls the DoSetup routine, which as its name sugg 
does the program peculiar setup tasks. In this case the progr 
menus are created, and a window with user informatio 
displayed briefly. The program's main event loop is entered 
the routine DoSelect is called. When the while condi 
evaluates to true, the program exits. 

VIP is in reality a high level ROM language that provic 
mouse driven set of templates for filling in automatically 
necessary calls to the toolbox to create windows, menus, ev 
and quickdraw functions. While Lightspeed C and Pascal 
you a feeling of "instant" in compiling and running progr: 
VIP is another order of magnitude above that in the ease 
speed of testing and trying various toolbox options. Variable 
defined and assigned in boxes with the mouse so that chai 
such as the type of window to display can be made in a way 
makes interactive BASIC seem like a chore. A quick click o 
mouse, and the program puts up a new type of window! Ex 
mentation with the toolbox is easy and educational in 
environment. 

The DoSelect routine includes the get next event proce 
and directs program flow according to event type. VIP kn 
about events and pre-defines the events for most program fi 
tions so that event driven programming is greatly simplifie 
type 1 event results in a call to the DoMenuSelect routine. 
switch logic form branches to handle selection of the File, ] 
or Option menus. Each corresponding routine, DoFile, Dol 
or DoOptions now determines the action to take as a result 
menu item selection. A type 4 event is processed when a clic 
a window close box is detected, and the routine DoClose 
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> details. Type 5 events 
andled by the procedure 
logEvent. 


Wait a minute... 
һе process of creating a 
нег program, regardless of 
anguage used, normally 
t start by writing specific 
Whether you subscribe to the 
)wn', bottom up’, or my per- 
favorite - 'omphaloskepsis' 


iat one on your spell checker) method of computer pro- 
ning, you will need to do a little designing. 

"ime spent in program design will save development time 
implify the coding process. However, the design and 
g phases are not mutually exclusive activities, nor are they 
sarily serial in occurrence. Before any of the code for this 
am was created, I had the concept of what I wanted the 
am to do. I knew that I wanted to demonstrate the use of 
s, dialog, windows, and events. I also knew I wanted 
es to store and retrieve data from disk, and to do some 
1etic using a couple of V I.P.'s intrinsic functions. Well, as 
ап imagine, that brief concept hardly constituted a design, 
n not one to let mere details stand in my way of having fun. 
f I go simultaneously designing and coding. I'm not 
ating this approach for others, it's just how my fragmented 
works, and V.I.P. is very accommodating to this approach. 


Main revisited 

\ main routine is required in all executable V.I.P. pro- 
. Program execution always begins in main, and a number 
isekeeping tasks such as initializing global objects, and a 
| of other 'who cares' stuff is performed automatically by 
Asa general guideline, the main routine in a well designed 
am should do a minimum amount of work. The first thing 
does is call the routine, DoSetup. DoSetup defines the 
s used by the program, and to add a little visual effect, a 
yw as shown in figure 2 is displayed briefly. Of course, in 
ram of your own design, the actions to be performed by this 
е would be different. V.I.P. also offers the ability to create 
s, windows, dialogs, etc. as resources, which could be 
d by this routine if desired. 

Whenthe DoSetup routine has completed its tasks, program 
tion resumes in main. The while logic form sets up the 
event loop of our program, which says in effect; While Quit 
all the routine named DoSelect, and whenever Quit z 0, 
So, how did Quit get the value of 0 to begin with, and why 
'tthe expression shown in the program listing say Quit = 0? 
questions; which gives me the opportunity to talk about 
land local objects. The symbol 'Quit' was declared to be a 
lobject of type ‘byte’ by clicking on the 'b' icon in the upper 
of icons to the left of V.I.P's Editor window. (Remember, 
s programming by mouse; all the language commands are 


DoSetup 
DoSelect 


DoMenuSelect 


DoC | oseBox 


DoDialogEvent 


DoOp tions 


Figure 1 


VIP's Automatic Flow Charts 


accessed from the on-screen icon lists!) Typing Quit in the 
dialog's text edit field, clicking the Global radio button, and 
clicking ‘Insert’, completed the declaration. 

Global objects which are not specifically initialized to a 
particular value, are automatically allocated static memory with 
a value of 0 at the start of program execution. Ergo Quit = О until 
we change it. Global objects, as the name implies, have meaning 
to all of the routines in a program. Global objects are said to be 
declared outside of main, and as noted in the program listing, 
that's where they are. (They are assigned relative to A5 by VIP 
like other Mac languages, but the programmer doesn't need to 
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[Storage class | Duration | Scope - 


Rutomatic Local 


Temporary 


Static Persistant | Global 


Figure 3 
VIP Objects 


worry about the details.) The second part of the question; why 
isn't the expression ‘Quit = 0? Well, it is. It's just written in a 
different fashion. The character '!' represents the logical ‘not’. In 
V.I.P. falsity is 0, and anything else is true. So by saying, while 
! Quit, we are saying in effect; while Quit = 0, or false, DoSelect. 
Take a look at the DoFile routine and you will see that the value 
of Quit is changed to 1 (true), and the program breaks out of the 
while loop and dutifully exits. 

Local objects, on the other hand, are known only to the 
routine in which they are declared, and appear in the program 
listing just below the routine's name. Local objects belong to the 
automatic memory class, which isn't a particularly important 
piece of information. What is important, is the fact that the initial 
value of local objects is indeterminate, and cannot be predeter- 
mined at the beginning of a routine. Figure 3 is a table showing 
the characteristics of V.I.P. objects. 

Since VIP objects include bytes, integers (long), reals, 
points, rectangles, and constants, one might wonder just how 
string variables are declared. This is not clearly brought out in the 
manual. A string variable is declared as a one dimensional byte 
array of length 255. The CopyString function is used to initialize 
the variable, rather than theassign statement. Clicking on the "cc" 
icon produces the list of string functions of which CopyString is 
one. 

Routines can call other routines and they may communicate 
with each other by passing arguments. V.I.P. allows up to 64 
arguments to be passed to the called routine. When the 'Routine 
Сай icon is clicked, a dialog asking how many arguments is 
displayed. Type in the appropriate number; 0 to 64, and click 
‘OK’. The Routine Call box is introduced in V.LP.'s Editor 
window with its input window open. Figure 4 shows the Routine 
Call 'DoMenuSelect as noted іп the program listing in the 


E DoMenuSel ect | 


are rame 1 


e 
arqument2 «| 
e 


Ез Неге 


argument2 2 
уе E EXER RUE] 


Figure 4 
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DoSelect routine. In the printed listing, the arguments to be 
passed are contained within parentheses immediately following 
the name of the routine to be called. In the DoSelect routine, 
EventID, EventMessage, and EventType have been declared to 
be byte objects, and MouseLocation is a point object - all local to 
the DoSelect routine. One problem with such a visual program- 
ming environment is that it is hard to communicate the program 
intent. The print function does print the guts of the program, but 
re-producing a VIP program from such a listing is harder than just 
creating your own visual program from the program's intent! A 
VIP program is an example of dynamic documents that really 
want to be shared and passed on a network rather than be reduced 
to paper. Itsa little like trying to describe a MacPaint picture from 
a written description! 

By selecting Set arguments... from the Routines menu, a 
dialog as shown in Figure 5 is displayed allowing the program- 
mer to specify the order and type of arguments being passed to the 
called routine. The order of the arguments is very important to 
assure that argument passing between the calling and called 
routine is done correctly. The arguments defined for the Routine 
Call 'DoMenuSelect (figure 4), will be successively assigned to 
their counterparts in the DoMenuSelect routine, i.e. menu and 
item. There must be an exact match of the number of arguments, 
their order, type and dimensions. Various object types can be 
defined in this dialog by specifying a number from 1 to 5 
representing object types Byte to Rectangle respectively. Argu- 
ments may be defined to be either 'input' or 'output by clicking 
the appropriate radio button. An input argument can only be read 
in the called routine, while an output argument can also be 
modified. The choice between the two depends upon the use 
envisioned by the programmer. 


Where were we? 

Let's start with a little refresher in creating a V.I.P. program 
by following the printed listing. Open V.I.P. and select New from 
the File menu. The first item in the listing is the routine call 
DoSetup. Click on the routine call icon, and when the argument 
dialog appears, enter 0, as we don't need to pass any arguments 
to this routine. Click OK, and enter the name of the routine to be 
called, i.e. DoSetup. Continue by clicking just below the routine 
call box to position the insertion arrow, and click on the while 
logic form icon. Enter the expression as shown within the 


parentheses following while. Again position 
the insertion arrow by clicking just below the 
'T in the while loop, and enter the routine call 
for the DoSelect routine as above. Click out- 
side of the while loop and select the procedure 
exit to complete the main routine. 

Select Set Routine... from the Routines 
menu, type DoSetup in the text edit field, and 
click insert. Do the same for DoSelect. Double 
click the routine call box to go directly to the 
DoSetup routine. Click on the menu class icon, 
select new menu in the selection dialog and 


[2 
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Ed T 
type [1] 


@ input 


Data Definition Dialog Box (Modal!) 


click the Select button. The new menu procedure is now 
immediately displayed in V.LP.'s Editor window with its input 
window open ready for programmer entered arguments. 

For title, enter "File" (Don't forget the quote marks.), and for 
menu, enter menu[1]. Continue by clicking the down arrow to 
close the procedure's input window, and click just below the 
procedure to position the insertion arrow for the next procedure. 
Click on the menu class icon again, select append menu item 
from the list and click the select button. Enter the arguments for 
menu and menu item exactly as shown in the listing. Note 
semicolons are used to separate menu items, and the entire list is 
a character string enclosed in quotes. 

Now to save a little time, we can copy the first two proce- 
dures by shift clicking to extend the selection range. Select Copy 
from the Edit menu. As before click just below the last procedure 
to position the insertion arrow, and then select Paste. Edit the 
argument fields to match the listing for both procedures, and 
repeat again for the next set of procedures. 

By now I'm sure you have grasped the mechanics of V.I.P. 
programming, so from here on let's concentrate on the structure 
of our example program, and ГЇЇ depend on you to select the 
procedures, enter the arguments, and declare objects as shown in 
the listing. If you do make a mistake and paste something where 
you didn't intend it to be, there is an Undo command in the Edit 
menu. Other goofs of a syntactic nature will usually be caught by 
V.LP.. It's a good idea to save your work from time to time, and 
always before you run a program. 
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Figure 6 
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item * 
active window 
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item * 


DoSelect 

The DoSelect routine is made up of the get next event 
procedure, and a switch logic form having three active branches. 
Arguments for get next eventhave been declared to be local to this 
routine. The selector for the switch structure is the symbol 
'EventType', and case 1 will be selected if EventType =1, case 2 
if EventType =4, and case 3 if EventType =5. When an event 
occurs the get next event procedure records the fact by putting the 
value of the objects, type, location, message, and ID into the 
event queue. When the switch structure detects the symbol ' 
EventType' is equal to 1, 4, or 5, the appropriate routine call is 
made. Figure 6 is a table showing V.I.P.'s event handling tech- 
nique. 

DoMenuSelect 

The DoMenuSelect routine uses the ubiquitous switch 
structure to select which routine should be called to process the 
actions of the three menus іп our example program. DoFile, 
DoEdit, and DoOptions correspond to the menu names. Which- 
ever routine is called, it is passed the argument ‘item’, i.e., the 
menu item. 

DoFile 

In our example program the only actions to be performed 
from the File menu are Page Setup..., Print..., and Quit. Another 
switch structure (sound familiar?) switches based on the value of 
'item' which was passed as an argument by the DoSelect routine. 

Case 1 envokes the procedure set up page which requires no 
arguments. Case 2 is selected when Print... is chosen. An if logic 
form is used to check if there is an active window, and if not to 
display an Alert informing the user of that fact. Case 3 is selected 
when the fourth menu item is selected. The object Quit is 
assigned the value of 1, and the program quits. Remember that 
every item in a menu list is counted, even if it is disabled or is just 
a separator line. 

DoEdit 

The DoEdit routine is mostly for show. Edit menus are 
normally provided for use by desk accessories even if their 
functions aren't particularly useful in the host program. V.I.P.'s 
procedures, cut text, copy text, paste text, and clear text take care 
of these chores and require no arguments. 

DoOptions 


As before a switch struc- 
ture directs program flow de- 
pending on the value of the 
object 'item'. Now for the clever 
part. To test the functionality of 
our example program without 
the necessity of completing the 
details of each called routine, 
we simply put an Alert in each 
branch. These Alerts with 
appropriate messages serve as 
stubs giving visual indication of 
proper program execution. 
Later these stubs are replaced 


null event 

menu item 

keypress 
mouse click 
close box 
dialog item 
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with the specific code as desired by the programmer. For now, 
‘About’ is the only active routine in DoOptions. 

About 

This routine creates a fixed size document window using the 
dimensions specified by the set rect procedures. The new 
window routine is used to create our window. The new version 
of VIP, 2.14, has fixed a number of shortcomings regarding 
windows. Window type 7 now allows a fully functional window 
frame with a grow box, zoom box, close box and working scroll 
bars. Most of the window mechanics are provided for automati- 
caly, so in our example program here, the text displayed can be 
scrolled without our having to invent a scrolling routine. The 
same is true for the zoom and grow functions. Programmers 
familar with the toolbox will recall that new window trap is a 
complex operation with many parameters. In VIP, the process is 
simplified considerably. We specify the graf port rectangle, the 
displayed window rectangle, title and type. The window pointer 
returned by the ROM trap is managed in the overhead of VIP for 
us. A simple byte variable allows us to keep track of which of our 
windows we are looking at. 

A TEXT file is opened, and the text is displayed in the 
window by the load text procedure. The file is then closed . If 
desired, a printed copy of this window's text may be printed by 
selecting Print... from the File menu. When the user is finished 
reading the text, a click in the window close box is detected by the 
get next event procedure and the routine DoCloseBox is called. 
See figure 7. 

DoCloseBox 

Gee, I bet you can't guess what this routine does. Well, just 
in case; an if logic form checks to see if a window called Window 
is theone to close. If itis, the procedures kill window and assign 
are executed, else do nothing. So far in our example program 
there is but one window which can be closed by clicking its close 
box, so the if statement is really superfluous. The assign 
procedure is used to restore the global value of 0 to Window to 
ensure the Print... selection will work properly after the window 
has been closed. 

DoDialogEvent 

DoDialogEvent is called when the get next event procedure 
detects an event of type 5. This routine is currently empty, and its 
details will be added in our next session. 

DoTryit 

This is not the name of a routine in our example program, it 
is rather my recommendation to you. In a future article we will 
explore the subject of Dialogs, records, saving and retrieving 
data from disk, and use a few of V.I.P.'s intrinsic functions. Add 
more menus, open additional windows, disable menu items when 
their selection is not appropriate, experiment, have fun. VIP is an 
addicting way to explore the Mac that does not require knowl- 
edge of a programming syntax. Why, I even taught my wife how 
touse it! Yet the real power of VIP may lie in its ability to produce 
old fashioned source code in a variety of languages. The VIP to 
LS C translator is now available, and a LS Pascal module is due 
out shortly. 

VIP to C 
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[This progrem wes designed to demonstrate some of the most 
common features of a typical Macintosh application, i.e., 
Menus, Windows, Dialogs, Files, and Events. 
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Spot Lit tach 


=o eo ee 


Have fun programming with V.I.P. 


CE 


Fig. 7 About Text File Display 


To convert our VIP program to C source code, we simply 
execute the VIP translator utility. This program reads our VIP file 
and outputs a C source text file. The Lightspeed project window 
in figure 8 shows the include files necessary to create a working 
program. All these files are either provided for by Mainstay, if 
they are VIP libraries, or in the case of the Unix files, are provided 
for in Lightspeed C. A ready-made resource file is provided that 
we must combine with our program file to create a working C 
program. Both the VIP and C versions of this program are 
included on our source code disk. As long as the files shown are 
included in the project, I had no trouble compiling and making 
the C program into a stand-alone application. As you look at the 
Clisting and compare it to the VIP listing, you'll see thateven the 
comments in our VIP boxes have been inserted properly into the 
code. It would be nice if there were some way to re-generate VIP 
programs from either the VIP program listing or the C source 
listing. As we mentioned previously, there is no good way to 
communicate a VIP program on paper, a real problem for 

programming journals! 

VIP Improvements 

There are two areas that jump out as needing attention in 
VIP. When programming by mouse, you tend to quickly define 
statements and variables on the fly. Once a variable is specified 
in a statement box, you must add the variable to the variable list 
as either a global or local variable. It would be natural to use the 
variable name in a new window procedure box for example, and 
then copy and paste the name into the objects window where the 
variables are defined. However, the objects window is a modal 
dialog box, and so the edit menu is locked out! This requires you 
to re-type the name of the variable from memory, a distinctly 
non-Mac'ish way to do things in a dynamic environment like 
VIP. 

The second design bug in VIP is the way in which you can 
move easily from one level to a nested subroutine. Because 
programming VIP involves working with what we will call a 
"dynamic flowchart", the program has a kind of ResEdit quality 
to it that lets you move from one procedure to another by clicking 
on the call box of the routine. This moves you down one level in 
the calling sequence to the nested routine. However, there is no 
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| PrLink.Lib 


| sprintf/sscanf 
strings 
unixatox.c 


| virPcLibi 


jiesso0000002600000000900000000000000000000400000000000020000000009090000000 0 0000500000009 өөө ө ө өз ө ө 


Fig. 8 LS C Project Files for VIP to C 


"pop-up" button to click to return you up one level to the previous 
routine you were working in. To get back, you have to go to the 
menu bar and re-select the routine by name to make it the current 
window display. Hence it's easy to move down a level into a 
subroutine, but a pain to come back up. 

The new version of VIP, 2.14, has fix a number of bugs and 
shortcomings so that the product now is very functional. With the 
addition of various translator programs, VIP may become a kind 
of universal programming language for the Mac. "Mouse up" a 
program in VIP, then translate it to the language of your choice: 
C, Pascal, even Ada! Then take the listings and compare them. 
Could be a whole new way to learn programming language 
syntax! 


VIP Program Listing (Text File) 


Menu(3) 
Quit 
Window 
result 


pain 


V.I.P. Demo program for MacTutor™ 
by Bill Luckie © 1987 


Visual Interactive Programming 
V.I.P. by Dominique Lienert 
Published by Mainstay. 
DoSetup 
while C! Quit) 

DoSelect 
exit 
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AboutF ile 
па1 


PortRect 
WindowRect 
set rect (50,40,312,472, WindowRect) 
set rect (0,0, 1000, 432, PortRect) 
new window (2,1, 1, WindowRect,PortRect, “About GC_ Dist", Window) 
open f ile ("AboutGCDist", 1, "TEXT", AboutF ile) 
load text CAboutFile, Window) 
close file CAboutF ile) 


V.I.P. Program listing notes. 


The listing sequence 1s: 


Global symbols and type 

Constants 

Main routine 

Other routines in alphabetical order 


Notes, if any, follow on next line after Routine's name. 
Arguments passed to а routine follow the routine's 


name and are enclosed in parentheses. Multiple 
arguments are separated by commas. 


--» Indicates ап input argument 
followed by type end symbol. 


«--» Indicates ап output argument 
followed by type and symbol. 


V.I.P. procedures and logic forms are printed in italics. 
Arguments or expressions entered by the 


programmer follow the procedure or logic form 
within parentheses, separated by commas. 


** This is & comment ** 


if (Window) 
kill window (Window) 
assign (Q0, Window) 
else 


--) byte item 


switch Citem,3,4,5,6) 
case 1 

cut text 
case 2 

copy text 
case 3 

paste text 
case 4 

clear text 
default 


DoFile Citem) 
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--) byte item 


switch Citem,1,2,4) 
case 1 


if (Window) 
print text (Window) 
else 
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alert C1,"There is no window to print from.",result) 
case 3 
assign C1,Qui t) 
default 


DoMenuSelect (menu, item) 


4% ез оз ө э ө з е э ө ө ө э з э ө э э э э е ө э з ө э э э ө в е э е з э э ө е з е е э э э э ө е э э ө ө э э э е ез е ө э о + 


--) byte menu 
--› byte item 


switch (menu, Menu[ 1], Menu[2 ], Menu (3]) 


cose 1 

DoFile Citem) 
case 2 

DoEdit Citem) 
case 3 

DoOptions Citem) 
default 
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--) byte item 


switch Citem, 1,2,3,5) 
case 1 

alert C1,"This is the Create. Records routine.",result) 
case 2 

alert C1,"This is the View. Records routine.",result) 
cese 3 

alert C1,"This is the Compute Distance... 
case 4 

About 
defeult 


routine." result) 


EventID 
EventMessage 
EventType 


MouseLocat ion 
get next event (EventType ,MouseLocation,EventMessage, EventID) 
switch CEventType, 1,4,5) 
case ] 
DoMenuSelect (EventMessage Event ID) 
case 2 
DoC loseBox 
case 3 
DoDialogEvent 
default 


Portrect 
Windowrect 


new menu C'File",Menu(11) 

append menu item (Menu[11, "Page Setup. . .;Print...;(-;Quit/Q") 

new menu C'Edit" ,Menu(21) 

append menu item KMenu[21, "CUndo/Z;C-;Cut/X; Copy/C;Paste/ 
V;Clear") 

new menu C"Options",Menu(3]) 

append menu item СМепи(3 1, "Create new Records...; View or Edit 
Records...; Compute Distance...;(-; About GC Dist") 

set rect (60,60, 120 450 Windowrect) 

sel rect (0,0,120,450,Portrect) 

new window (4,1, 1,Windowrect,Portrect, "" Window) 

set text font C0) 

move to (15,15) 

draw string C'V.I.P. Demo program for MacTutor™",@) 

move to (30, 145) 


© The Essential MacTutor, Vol. 3 


draw string С“ by Bill Luckie.",0) 
move {о (45,168) 

draw string C"9 1987",0) 

wait (200) 

kill window (Window) 


VIP Program "C" Listing 


include "VIPtoC.h" C 
/* Global symbols */ 


Version 


/* 

-------------- BIN -------------- 

V.I.P. Deno program for MacTutor™ 

by Bill Luckie 0 1987 

Visual Interactive Programming 

V.I.P. by Dominique Lienart, published by Mainstay. 
Ж 

main (С) 


VIP-Init С); 
vip-DoSetup СО; 
while C! Quit) 


( 
кле O0; 
н С); 


/* 
-------------- About -------------- 
*/ 


аны, С) 


char 

AboutF ile; 
Rect 

PortRect, 

WindowRect; 
VIP_set_rect 
CClong)(58), Clong (48), Clong (3 12), Clong (472), &WindowRect); 
VIP_set_rect 
€Clong)(8), Clong2C0), C1ong 2С 1000), Clong)( 432), &Por tRect); 
VIP_new_window 
(Cchar (2), Cchar 2C 12, Cchar 2C 12, WindowRect,PortRect, "About GC_ 
Dist", 

&Window); 

VIP_open_f ile ("AboutGCDist" , Cchar 2C 12, "ТЕХТ", &AboutF ile); 
VIP-load text ССсһаг )CAboutF ile), Cchar )(Window)); 
ыы ССсћаг )CAboutFile)); 


/* 

-------------- DoCloseBox -------------- 
*/ 

oe С) 


if (Window) 


VIP_kill_window CCcher2CWindow2); 
Window = 9; 
) 


) 

/* 

-------------- DoDialogEvent -------------- 
х/ 

натору С) 

) 


/* 
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-------------- DoEdit -------------- 


57 

vip-DoEdit Citen) 
cher item; 

m CClong)Citem)) 
case 3: 


VIP_cut_text 0), 
LU 


case 4: 


VIP_copy_text СО; 
break; 


case 5: 
( 


VIP_paste_text СО; 
break; 


case 6: 


VIP_clear_text (2; 
ix 


-------- ------ DoFile -------------- 
x 


/ 
vip-DoFile Citeam) 
cher item; 


( 
eiu (Clong2Citem2) 
case 1: 


VIP_set_up_page (2; 
break; 


case 2: 
if (Window) 
шаа CCchar )CWindow)); 


else 


( 
VIP_alert CCchar2C D, "There is no window to print 


Шалы 


dax 
case 4: 
Quit = 1; 
break; 
) 
) 
) 
/* 
mius cuu DoMenuSelect -------------- 
ui 
vip-DoMenuSelect Caenu, itea) 
char menu; 
char item; 


( 
if rata zz Menu[(1) - 1D 
и ССсћаг )Citem)); 


else if (menu == Menu[(2) - 17) 
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( 

vip-DoEdit ССсћаг )Citem)); 
else if (menu == Menu[(3) - 11) 

oo CCchar )Citem)); 


) 
/* 
-------------- Dodptions -------------- 
%/ 
vip-DoOptions Citem) 
cher item; 


mun (Clong2Citen2) 
cese 1: 
VIP.alert ((char)(1), "This is the Create_Records 
routine." &result?; 
break; 
case 2: 


VIP_alert CCchar2C12,"This is the View. Records 
routine." , &result); 
Ie 


cese 3: 
( 


VIP_alert CCcher2C D, "This is the Compute Distance... 


routine.", 
&result); 
break; 


case 5: 


vip_About (); 
break; 


) 
) 


/* 
-------------- DoSelect -------------- 
x 


не () 


cher 
Event ID, 
EventMessage, 
EventType; 
Point 
MouseLocation; 
VIP_get_next_event C&EventType, &MouseLocat ion, 
&EventMessage , &Event ID); 
d CClongX(Event Type?) 


cese 1: 
vip-DoMenuSelect 
(Cchar )CEventMessage ), (char )CEventID)); 
break; 
case 4: 


vip-DoCloseBox С); 
break; 


case 5: 


vip-DoDialogEvent (2; 
break; 
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) 
) 
) 
/* 
корыр ышкынын DOSetup ere 
*/ 


рор С) 


Rect 
Portrect, 
Windowrect; 


VIP_new_menu C"File",tMenu[C1D - 12); 

VIP_append_menu_item С(сһаг )(Menu[C1) - 11), "Page 

Setup. ..;Print...;(-;Quit/Q"); 

VIP-new.menu C"Edit",&Menu[(2) - 102; 

VIP_append_menu_item ССсһаг )(Menu[(2) - 11), "CUndo/Z; (-;Cut/ 
X;Copy/C;Peste/V; Clear"); 

VIP_newmenu C"Options",&Menu[C3) - 1); 

VIP. eppend. menu item CCchar)XMenu[C3) - 1), "Create new 
Records...;View or Edit Records...;Compute Distance...;(- 
;AMoout GC Dist"); 
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VIP-set.rect 

((1002(602,(10092(602, Clong)¢ 128), Clong2(450) , &Windowrect); 

VIP_set_rect 

CClong)(8), Clong)(8), Clong)C 128), Clong)( 458), &Por trect?; 

VIP_new_window 

CCcher (4), (char 2C DD, (char 9C 1), Windowrect,Portrect,"", 
&Window); 

ҮІР вес text font CCchar2(02); 

VIP_move_to (Clong)C15), Clong2C752); 

VIP- drew.string C"V.I.P. Demo program for 

MacTutor "" , (char )(8)); 

VIP_move_to CClong2C30), Clong2C 14522; 

VIP-drew.string С" by Bill Luckie.", (char (8); 

VIP_move_to CClong2C45), Clong2( 16822; 

VIP-drew.string ("9 1987",Ccher2(0)); 

VIP_wait СС1опд)С200)); 

p E ССсћаг )CWindow)); 


vip-drew.port (wndwID) 


cher wndwID; зм 
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C Workshop 


I'vealwayslikedthe method of present-  " 
ing “on-line help” information used by the E: 
Excel™ program. When I received the Light- 
Speed C™ V2.01 upgrade for the 128K 
ROMS, I created a similar kind of help func- 
tion while learning how to use some of the 
List Manager routines. This article presents 
my “help” function, and explains how to 
implement it in C, using the List Manager. 

The help dialog box is shown in Figure 
1. It contains an OK button and two boxes, 
one for the list of topics and one to show the 
help information for the currently selected 
topic. The help function builds the list of 
topics dynamically, using an STR# resource 
number passed to it by the calling routine. 
Each string in the STR# resouce contains a 
topic and a reference number. The reference 
number is the ID of a HELP resource. When- 


ever the user selects a topic, the ASCII text from the correspond- 
ing HELP resource is displayed in a scrollable TextEdit record. 

The code shown in Listing 1 consists of a very simple 
main() and an equally simple do_about() function, and the 
routines that make up the help function: do help(), read help(), 
show help(), help filter(), and help action(). 

do help() is called to start things off. It takes a single 
parameter, the ID of the STR# resource that contains the help 
topics to be displayed. By using a parameter in this way, it should 
be easy to introduce some context sensitivity into the help that 
gets displayed. do_help() reads in the STR# resource and gets the 
number of topics in the list. It reads the dialog resource for the 
help dialog window. The help list user item is then read in to get 
its dimensions. This information (dimensions and number of 
topics) is used to create the empty list structure with a call to the 
List Manager routine LNew(). Note that the List Manager re- 
quires that the dimensions include room for the scroll bar (if one 
is present). 

The read help() function gets the individual strings from 
the STR# resource and parses each one for a topic and an ID 
number. А backslash is used as the delimeter marking the end of 
the topic and the start of the ID number. As each topic is read in, 
it is added to the topic list by calling the List Manager routine 
LSetCell(). Its corresponding HELP ID number is stored in the 
array help id[]. Finally, the List Manager routine LSetSelect() is 
called to select the first cell as the starting point and LDoDraw() 
is called to make the list visible. 

The show help() function sets up the help text box by 
getting its dimensions from the second user item in the dialog 
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List Manager Inspires Help Function Solution 


кэн) Goer mere 


Dummy topic 1 
Dummy topic 2 
Dummy sub-topic 2.1 


Dummy sub-topic 2.2 
Dummy topic 3 
Dummy topic 4 

Dummy sub-topic 4.1 

Dummy sub-topic 4.2 йш! 
Dummy topic 5 (| [corresponding HELP resource is displayed | 


Fig. 1 Our help function demo in action! 


William Rausch 

Battele Pacific Northwest Labs 
Richland, WA 

MacTutor Vol. 3 No. 4 


Introduction К? [two boxes, one for the list of topics end one 
More info about HELP to show the help information for the T 


: ЕҢ icurrently selected topic. The function ИН 
|] [builds the list of topics dynamically, using E: 
1 а STR? resource number passed to it by ї 
in [the calling routine. 

| | Each string in the STR resouce contains 
ind ја topic and a reference number. The 

‘a [reference number їз the 10 of a HELP 

31] |resource. Whenever a the user selects e 

М topic, the ASCII text from the 


resource. (As with the topic list box, the user item is large enough 
to include the scroll bar as well.) The font and size are then 
specified. After some experimenting, I settled on 10-pt Geneva 
font. There is no reason you couldn’t select some other font for 
your application though. 

Once the help box is prepared, we load it with the HELP 
resource that corresponds to the first topic in the list (since that 
topic is selected when the help dialog first appears on the screen). 
This is done by merely reading in the HELP resource designated 
by help id[0]. A HELP resource is merely composed of ASCII 
text, and it is copied directly into the TextEdit record using the 
TEInsert() routine. Finally, the need for a vertical scroll bar is 
checked, and if it is, then it is activated and the proper maximum 
value is set using SetCtlMax(). Then, we repeatedly call Mo- 
dalDialog() until the user clicks OK (or hits Return). At that time 
we dispose of the various data structures and return. 

The interaction with the user is controlled by the 
help filter() function passed to ModalDialog() as a filterProc. 
(Note that help filter() is declared as 'Boolean Pascal'. This is 
because it will be called by the ROM routines and needs to 
conform to the expected way of passing parameters.) Since it gets 
to examine every single event that occurs while the modal dialog 
isrunning, itis very easy to respond to user actions. Basically, the 
routine is nothing but a switch statement on the type of event. On 
an updateEvt it redraws the user items (our two boxes). On a 
keyDown it checks to see if it was a Return and, if so, tells the 
calling routine that the OK button was selected. On a 
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mouseDown,it may perform a number of activities as we will see. 
For any other event, it does nothing. 

To handle a mouseDown event, the function first checks to 
see if the mouse was clicked in a scroll bar. If it was clicked in our 
help box scroll bar, TrackControl() is called. TrackControl() is 
called with or without an actionProc depending on whether the 
mouseDown occured in the “thumb” or elsewhere in the scroll 
bar. If the mouseDown occured in the thumb, the help text is 
scrolled after the call to TrackControl() returns. If the 
mouseDown occured in some other part of the scroll bar (up or 
down arrow, up or down page), the function help action() is 
passed as an actionProc. (As with the filterProc previously 
discussed, it is declared as a ‘Pascal’ function, but of type void 
since it doesn't return a value of any type.) help action() merely 
checks the partcode it is passed, gets the current value of the scroll 
bar, and scrolls the text up or down as neccessary to accomodate 
the user’s actions. The up and downarrowscause the text to scroll 
one line at a time; the up and down pages cause the text to scroll 
five lines at a time. 

If the click occurred in the List Manager’s scroll bar, call the 
routine LClick() to handle it. If the click was not in a scroll bar, 
check to see if it was inside the topic box. (A Rectis the first item 
of the List Manager's data structure; hence the “*h.help_list” 
used for the Pt/nRect() call.) If so, call the LClick() routine and 
see if the user has selected a new topic. Do this by comparing the 
cell number returned from a call to LGetSelect() with the one 
saved in h.last_one. If the selected topic has changed, delete the 
help text currently stored in the TErecord and replace it with the 
HELP resource corresponding to the new topic. Then, update 
h.last_one with the new cell number. 

Any other type of event is ignored by the filterProc and is 
left to the ModalDialog() function to handle. When the user 
finally clicks the OK button (or hits Return), the while() loop 
surrrounding the call to ModalDialog() (in show help()) com- 
pletes and we clean up after ourselves by disposing of the various 
data structures we created. 

The help dialog resource just contains three items: 

1) an OK button, 2) a user item for the help text, and 

3) a user item for the topic list. 
This resource is easy to create using ResEdit. It doesn't matter 
what shape or size the user items are or where in the dialog they 
are located. Just make sure that they include enough space for the 
scroll bars to fit alongside your text. 

The HELP resources are just ASCII text. I created mine 
using ResEdit 1.1-D. It would be easy to write a simple program 
that would take text from an editor file and convert it into a HELP 
resource. No special formatting is necessary (however, be sure to 
use just normal printing ASCII characters that TextEdit knows 
how to handle). The topic lists are just as simple. Create an STR# 
resource, where each string contains the topic, a backslash, and 
the ID number of a HELP resource (see Figure 2). [To give you 
the big picture of how this is done, the resource file was "de- 
compiled" with DeRez and "re-compiled" with Rez. The re- 
source listing at the end of the article is the Rez input file, with 
the hex data for the help strings removed to save space. Note that 
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HELP "intro" ID = 1 from help.rsrc 


00000000 2020 2054 6869 7320 
00000008 


000000 18 


- 
JAO farm 


7573 6564 2074 6F20 used to 


numStrings 17 


The string 


IntroductionM 


[oummu topic 1\100 | 


Fig. 2 STR# Resources for topic headlines 


the STR# resources in Rez format appear to have an extra 
backslash, but this is apparently the Rez formatting character as 
figure 2 clearly shows a single backslash seperating our topic 
from the ID number of the help resource. -Ed] 

To conclude, I think that this on-line help function is an 
easily implemented, yet powerful, method of presenting infor- 
mation to a user. The major advantage when compared to Excel 
and other such programs is that it allows you to more easily 
peruse information about multiple topics. The ability to easily 
present context sensitive help is another bonus. 


The string 


The string 


The strinq 


Listing 1: C source code for the help demo program 


6 File Edit Search Project S 


: MacTraps 
7 storage 
trings 


Fig. 3 LS C Link Window 


/RARRREAAAAAAAAAAAAAERAAAAAAA KAA AKA AKA AAA AAA AK KKK 


* help.c - demo program shows а new way to 
z present on-line help 

x 

* Bill Rausch, Jan 1987 


* Uses LightSpeed C™ (Think Technologies, Inc.) 
KXXXXXXXEXEXEXEXEEXYXXEXYXEEXYXYXEXEXYXXrrxkxxxit/ 


®include «EventMgr .h> 
®include «MenuMgr .h> 
8include <WindowMgr .h> 
8include <ToolboxUtil.h» 
include «DialogMgr.h? 
include <FontMgr .h? 
include «TextEdit.h» 
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*include <ListMgr .h) 
“include <strings.h) 
*include «pescal.h? 


def ine NULL ØL 
tidef ine ACTIVATE 0 
дег ine INACTIVATE 255 


define FILEID 256 
define ABOUT 1 
#def ine HELP 2 
define QUIT 3 


define HELP. DLG 256 
define HELP.OK 1 
"def ine HELP. BOX 2 
def ine HELP_LIST З 


def ine HELP. STR 256 /% STR® containing topics */ 
üdef ine MAX-HELPS 100 /* application dependent */ 


struct ( 
Rect text box; /* user item dimensions */ 
Rect topic.box; /% user item dimensions */ 
TEHandle text; 
ListHandle topics; 
Rect d.rect; /* TextEdit's dest rect */ 
Rect v.rect; /* TextEdit's view rect */ 
int offset; /* d.rect vertical shift */ 
int lines.vis; /* number of lines visible */ 
ControlHandle text_scrol1; 
int max_text; /* max value of scroller */ 
int help_id{MAX_HELPS]; /* topics’ HELP IDs */ 
int num topics; /% how many topics? */ 
d Tast_one; /* last cell clicked in */ 
д 


pascal Boolean help_filter(); 
Boolean show_help(); 
pascal void help_action(); 


ХХХ ХХХ ХХХ ХХХ SAAS AAA AAA AES ХХХ EAA KATES 
ж Trivial main€), just enough to use а single 
x menu with only three items: About..., Help..., 
* and Quit. No DAs, no windows, no command key 

* equivalents or other key strokes. */ 

nainC) 


EventRecord the event; 
WindowPtr which window; 
int menu_id, item number; 
long menu.code; 

int window. code; 
MenuHandle f ilemenu; 


FlushEventsCeveryEvent, 0); 
InitGref C&thePor t); 
InitFonts(); 

InitWindows(); 

InitMenus(); 

TEInit(); 
InitDialogsCNULL); 


filemenu = GetMenuCFILEID); 
InsertMenu(filemenu, 0); 
DrawMenuBar C ); 
InitCursor(); 
for (;;) /* event loop */ 
if (GetNextEventCeveryEvent, &the_event)) 


M inii == mouseDown) 
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window_code=F indW indow( the_event . where, &which_window); 
ч cuc == ігМепиВаг) 


menu_code = MenuSelect(the. event . where); 
menu. id = HiWord(menu. code); 

item number = LoWord(menu_code ); 

if (menu id == FILEID) 


( 
if Citen number == ABOUT) 
do_about¢ 
"Help demo - Bill Rausch - Jan. 1987", 
"LightSpeed C™ by Think Technologies"); 
else if Citem. number == HELP) 
do. helpCHELP. STR); 
else if Citem number == QUIT) 
ExitToShe11C); 
else 
SysBeept( 1); 


HiliteMenuC0); 
И 


else 

SysBeep( 1); 
else 
SusBeep( 1); 


) 
) 


ХХХХХЗ ХХХ ХЕ хх ХХХ ХЕ ХХХ kg dodo bx / 
/* creates alert-like box, waits for mouseDown */ 
do-sboutCtext1, text2) 

d *text1, *text2; 


/* 
x 
x 


є »* »* и и 


x 


long dummy; 

Rect box; 

Rect line; 

GrafPtr old.port; 
WindowPtr window; 
EventRecord en event; 


SetRect(&line, 6, 5, 345, 255; 

SetRect(&box, 75, 125, 425, 180); 

window = NewWindowCNULL, ох, "", TRUE, 
dBoxProc, -1L, TRUE, NULL); 

GetPortC&old. port); 

SetPort(window); 


Tex tFontCsystemFont); 

TextBoxCtexti, Clongstrien(text1), &line, 
teJustCenter ); 

OffsetRect(&line, 0, 28); 

TextBoxCtext2, Clong)strien(text2), &line, 
teJustCenter ); 


GetNextEventCeveryEvent, &en event); 
) while Can_event.what != mouseDown); 


DisposeWindow(window); 
ымы 


ЖХХХХХХХХХКХХХЖХХХХХХХХХХХХХХХХХХХХХХХХХХХЖХ ЖЖ 
Help routine that makes use of the List 
Manager to present user with a list of topics 
and help text about each one. The topics are 
stored as a STR® resource and the help texts 
ere stored as HELP resources. Each topic 
string contains the number of its associated 
HELP resource. 

Note: requires Geneva 10 font to be present */ 
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do. help(str. id) 
"n str id; 


DialogPtr the. dialog; 


Handle scr. handle; /* scratch variable */ 
int scratch; /* scratch variable */ 
Str255 scr.str; /* scratch variable */ 


Rect hdata.rect; /* for list manager setup */ 
Point cell_size; /* for list manager setup */ 
Handle topics; /* for list manager setup */ 
int *n_t_ptr; 

GrafPtr old_port; 


/* Read STR, get number topics */ 
topics = GetResourceC'STR*', str. id); 
h.num_topics = *Cint *)(*topics); 


/* Read dialog box resource */ 

the.dialog = GetNewDialogCHELP_DLG, NULL, -1L); 
GetPort(&old_port); /* save where we were */ 
SetPortCthe. dialog); 


/* get user item for topic list */ 
GetDItemCthe dialog, HELP.LIST, &scratch, 
&scr_handle, &h.topic box); 
InsetRect(&h. topic_box, 1, 1); 
/* leave room for vertical scroll ber */ 
h.topic_box.right -= 15; 
SetRect(&hdata_rect, 0, 0, 1, h.num topics); 
SetPt(&cell.size, h.topic_box.right - 
h.topic_box.left, 16); 


h.topics = LNewC&h. topic_box, &hdata_rect, 
cell.size, 9, thedialog, 
FALSE, FALSE, FALSE, TRUE); 
(*h. topics)-»selFlags = 10nly0ne; 
/* restore rect for framing */ 
InsetRect(&h. topic_box, -1, -1); 
read_helpCh.topics,h. nun. topics, h.help_id, str_id); 


if C!show.helpCthe. dialog, h. topics, 


do. sbout C "shoRR&lgcid 2? 
"returned ап error."); 


ананы /* put us back */ 


/RESEREREAAAAAE AAAS AEA ER GIOICOIOOIGDOOOOIOOE RAK IG IGIOIOIOEOK XE 
х Read the topics from the STR® resource. Add 

* them to the List as they are read. Also, save 
* the IDs in an array for use later in finding 
* the proper HELP resource to display for each 
* topic. */ 

read.help(topics, num topics, help_id, 

str. id) 

ListHendle topics; 

int num topics; 

int help. 1411; 

m str_id; 


int i; 

Str255 a_topic; 
Point the.cell; 
char *id. number; 
$tr255 strver; 


for Сі=0; i«num topics; i++) 
GetIndString(a-topic, str id, 1+1); 
PtoCstrCa- topic); 
id.number = strchrCa_topic, Cchar)'\\'); 


/* terminate topic and point to number */ 
*idnumber++ = '\0'; 
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help_idli] = atoiCid number); 


SetPt(&the_cell, 0, i); 
LSetCellCa_topic, strienCa_topic), the. cell, 
topics); 


SetPt(&the_cell, 0, 0); 
LSetSelect((Boolean)TRUE, the.cell, topics); 
y o Reese ыы. topics); 


ЫЫ ыы ыы TAKA AA AAR AAR AK AKER ARES 


* Set up the help text for the first topic in 
* the list. Call ModalDialog (with a filterProc 
* to do all the work). Loop until user clicks 
* OK. х/ 
Boolean show.helpCthe.dialog, topics, help_id) 
DielogPtr the.dialog; 
ListHandle topics; 
int help. id[]; 


GrafPtr old_port; 

int item hit; /* returned by ModalDialog */ 
int scr. int; /* scratch variable */ 
Handle scr_handle; /* scratch variable */ 
Boolean done = FALSE; 

int i, buf_size; 

Rect scroll_rect; 

Handle the_help; 


/* get user item for help text */ 
GetDItemCthe.dialog, HELP_BOX, &scr_int, 
&scr_handle, &h.text. box); 
/* leave room for scroll bar */ 
h.text.box.right -= 16; 
scroll.rect.right = h.text.box.right + 15; 
scroll.rect.left = h.text box.right - 1; 
scroll.rect.top = h.text. box. top; 
scroll.rect.bottom = h.text box.botton; 
h.text.scroll = NewControlCthe. dialog, 
&scroll.rect, "", TRUE, 
0, Ø, Ø, 16, NULL); 
HiliteControlCh.text.scroll, INACTIVATE); 


/* Set up TextEdit record for the help text */ 
h.d.rect.top = h.text_box.top + 1; 

h.drect. left = h.text_box.left + 1; 
h.d.rect.right = h.text.box.right - 1; 
h.d.rect.bottom = 20000; /* infinity */ 
h.v.rect = h.text. box; 

InsetRect(&h .v. rect, 1, 1), 

h.text = TENewC&h. d.rect, bh. v.rect?; 

(*h. text) txFont = geneva; 

(*h. text) txSize = 10; 


h. last_one = 0; /* 1st topic selected */ 

h.offset = 8; /* at top left corner now */ 

h.lines.vis = (h.v_rect.bottom - h.v_rect. top) 
/ Оһ. text)-> lineHeight; 


/* put Ist topic’s text into help box */ 
the_help = GetResourceC'HELP', help. id[21); 
buf -size = SizeResourceCthe. help); 

TEDeact ivateCh. text); 

TESetSelect(32767L, 32767L, h. text); 

HLock( the_he 1p); 

TEInsert(*the. help, Clong)buf_size, h. text); 
HUn lock( the_he 1p); 


/* vertical scroll bar necessary? */ 
if ССР text)-»nLines › h.lines_vis) 


HiliteControlCh.text. scroll, ACTIVATE); 
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h.max text = СССҰћ. text) nLines) - 
h.lines.vis) * C*h.text)-»lineHeight; 
қыны h.nax text); 


Ы ады ы 
do 
ModalDialogChelp_filter, &item hit2; 
if Сіќет hit == HELP_OK) 
done = TRUE; 
) while (!done); 


TEDisposeCh. text); 
LDisposeCh. topics); 
DisposDialog( the_dialog); 
d TRUE; 


ХХХ АХАЖ ХХХ ХХХ ХХ ХХХ ХХХ ХХХ EXXXXXXX 
* This routine handles activating and updating 

* of the scroller and the box erea. We must 

* handle mouse downs in the scroller and text 

* box, passing back TRUE, and pass FALSE back 

* for everything else so the Dialog Manager does 
* his thing on the other items. */ 

pascal Boolean help.filter(dp, ep, ip) 

WindowPtr dp; 

EventRecord *ep; 

int *ip; 


int part; 

ControlHandle ch; 

cher tempcher; /* check keydown for RETURN */ 
Point mouse. loc; 

int stert value, end. velue, dummy, delta; 

long а_се11; 

int cell.num; 

Handle the.help; 

int buf size; 


int scr. int; /* scratch variable */ 
Handle scr.handle; /* scratch variable */ 
Rect scr_rect; /* scratch variable */ 


switchCep-> what) 


case updateEvt: 
/* is the update event for this window? */ 
if Cep-»message == (long dp) 


/* outline default button */ 
GetDItemCdp, HELP_OK, &scr_int, 
&scr_handle, &scr_rect); 
InsetRect(&scr rect, -4, -4); 
PenSize(3, 3); 
FremeRoundRect(&scr.rect, 16, 16), 
PenNormal(); 
/* draw boxes around topics, text */ 
FrameRect(&h. topic_box ); 
FrameRect(&h. text box); 
/* update contents of boxes */ 
EreseRect(C&h . v. rect); 
TEUpdateC&h.v. rect, h.text2; 
LUpdateCdp->»visRgn, h. topics); 


return FALSE; 


case keyDown: 
/* convert return key to OK button */ 
tempchar = BitAndCep->message, 
charCodeMask ); 
if Ctempchar == '\г') 


*ip = HELP_OK; 
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return TRUE; 
return FALSE; 


case mouseDown: 
/* get our own copy of coordinates */ 
mouse_loc = ер-› where; 
Global ToLocal (&mouse_loc); 


pert = FindControl(mouse_loc, dp, &ch); 
a › 0) 


/* is click in а scroll ber? */ 
if (ch == h. text. өсго11) 


ам == inThumb) 
аи mouse_loc, NULL)) 


/* reposition help text */ 
delta = h.offset - 

GetCtlValueCh. text_scrol1); 
ТЕӘсго11(0, delta, h. text); 
нн -= delta; 


) 
else 
TreckControlCch, mouse. loc, 
help_action); 
return TRUE; 


else if (ch == (*h. topics)-»vScrol1) 


LClick(mouse_loc, ep->modif iers, 
h. topics); 
pm TRUE; 


else 
return FALSE; 


else if (PtInRect(mouse_loc, *h. topics)) 


/* click was in topics list so find which 
* topic wes selected and display the 
* proper HELP resource */ 
LClickCmouse_loc, ep-)modifiers, 
h. topics); 
а_се11 = 0; 
if K(LGetSelectCTRUE, %а се11, h.topics)) 
cell.num = HiWord(Ca.ce11); 
if Ccell_num >= 0 && 
cell_num != h. last one) 


/* get rid of the old text */ 
TEDeact ivateCh. text); 
TESetSelect(OL, 32767L, h.text); 
TEDeleteCh. text); 

if (cell -num < h.num topics) 


(һе һе1р = GetResourceC'HELP', 
h.help-id[ce11.num1); 
buf_size = SizeResourceCthe help); 


else /* no topic selected so no help */ 
buf_size = 0; 
if (buf_size › 0) 


HLock(the_help ); 

TEInsert(*the_help, Clong)buf_size, 
h. text); 

asa 


/* reset the scroll ber */ 


© The Essential MacTutor, Vol. 3 


SetCtlValueCh.text. scroll, 0); 

/* reposition the help text */ 

delta = h.offset - 
GetCtlValueCh.text. өсго11); 

TEScro11C0, delta, h. text); 

h.offset -= delta; 

/* scroll bar necessary? */ 

if (Ch. text) пі ines > h. lines vis) 


HiliteControlCh.text. scroll, 
ACTIVATE); 

h.max text = (((*h. text)-»nLines) - 
h.lines_vis) * 
(*h. text )-> lineHeight; 

аа ыы. h.max text); 


else 
HiliteControlCh.text. scroll, 
INACTIVATE); 
/* finally, save the new topic */ 
h.lest.one = cell.num; 


) 
ыш TRUE; 
return FALSE; 


default: 
return FALSE; 


) 


[*XXxXocooooooooeoopeeoooopoocoeooeeoboeeoooobobopbeoeobeoeer 
* This routine is called by the Toolbox while 

* executing the TrackControlC) routine. It has 

* to teke care of scrolling the text when the 

* up/down arrow and page parts of the scrollbar 
* are clicked in. */ 
pascal void help_action(the_scroll, partcode) 
ControlHandle +ће_ѕсго11; 

B partcode; 


int value, delta; 
шш (рәгісоде) 


cese inUpButton: 
value = GetCtlValueCthe.scro112; 
value = (value-C*h. text)» lineHeight > 0) 
? value-C*h. text)-> lineHeight 
: Ø; 
SetCtlVelueCthe. scroll, value); 
break; 
case inPageUp: /* move 6 lines at a time */ 
value = GetCtlValueCthe. scro112; 
value = (value-6*C*h. text)-? lineHeight > 0) 
? value-6*C*h. text)-»lineHeight 
: £; 
SetCtlValueCthe. scroll, value); 
break; 
case inDownButton: 
value = GetCtlValueCthe.scro11); 
value = (value + (*h. text)-» lineHeight < 
h.max_text) 
? value + (*h. text)-» lineHeight 
: h.max_text; 
SetCtlValueCthe scroll, value); 
break; 
cese inPageDown:/* move 6 lines at a time */ 
value = GetCtlValueCthe. scro11); 
value = (value + 6*(*h. text)-» lineHeight < 
h.max_text) 
? value + 6*C*h. text)-) lineHeight 
: h.max text; 
SetCtlValueCthe.scroll, value); 
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break ; 


delta = h.offset - GetCtlValueCh.text. өсго11); 
ТЕ$сго11(0, delta, h.text2; 
аны -= delta; 


ЫЫ 522552 225 522 52223 32 222 2222222222222222222225224 


* atoi.c - much smaller than unix & stdio libraries 
x 
* WN Reusch 


* January 1987 
MAKE KAKA AKER EERE AEA EK EES EKER EK AEA AAA ХХХ RE ХХХ АХЖ ERE / 


8include <MacTypes .h> 
8include «pescal.h? 
include <strings.h> 


"define isspace(c) (c == ' ' || с == '\{') 
"define ZERO 48 


/®ЖЖЖЖЖЖЖЖАЖАЖЖЖАЖАКЖААЖАКЖАХЖЖЖЖЖЖЖЖЖУЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ у 


etoiCstring) 
register char *string; /% must be NULL terminated */ 


register long answer = ØL; 
Boolean negative = FALSE; 


while Cisspace(*string)) 
stringt*; 

if (*string == '-') 
negative = TRUE; 

while (*string) 


answer = (answer * 10) + (*string - ZERO); 
string+t; 


if (negative) 
answer = Ø - answer; 
return CintJanswer; 


/* Resource File for Help.rsrc in Rez MPW Format. Note that 
the help string resources are given here in ascii format and 
should be typed in with ResEdit as in this form, Rez probably 
will gag. */ 


resource 'DITL' (256, "help", purgeable) ( 
( /* array DITLerray: З elements */ 
/* (1) */ 
(244, 171, 263, 243), 
Button ( 
enabled, 
" OK " 


); 
/* 12] */ 
(36, 172, 231, 401), 
UserItem ( 
enabled 


7 
/* [3] */ 
(36, 7, 231, 165), 
UserItem ( 
enabled 


) 
); 
resource 'DLOG' (256, "help", purgeable) ( 
(40, 52, 314, 460), 
dBoxProc, 
invisible, 
noGoAway, 
0x0, 
256, 
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“hel р" 


resource 'MENU' (256, "File", preload) ( 


256, 
textMenuProc, 
el lEnabled, 
enabled, 
"File", 
( /* array: 3 elements */ 
/* (1) */ 
"About...", noIcon, noKey, noMerk, plain; 
/* [2] */ 
"Help demo...", noIcon, noKey, noMerk, plain; 
/* [3] */ 
"Quit", noIcon, noKey, noMark, plain 
); 
resource 'STR®' (256, "help topics") ( 
( /* array StringArrey: 17 elements */ 
/* (1) */ 
"IntroductionW 1" ; 
/* [21 */ 
"More info about HELP\\7"; 
/* (3) */ 
"And even more\\4"; 
/* (4) */ 
"Dummy topic 1\\100"; 
/* (5) */ 
"Dummy topic 244101"; 
/* (6) */ 
" Dummy sub-topic 2. 114200". 
/* [Т] */ 
" Dummy sub-topic 2.2201"; 
/* (8) */ 
"Dummy topic 3\\480"; 
/* [9] */ 
"Dummy topic 4\\333"; 
/* (10) */ 
" Dummy sub-topic 4. 14334", 
/* 011] */ 
" Dummy sub-topic 4.2\\332"; 
/* (12) */ 
"Dummy topic 514300". 
/* [13] */ 
"Dummy topic 614500". 
/* (141 */ 
” Dummy sub-topic 6. 1\\332"; 
/* [15] */ 
" Dummy sub-topic 6.2 X332"; 
/* [16] */ 
Dummy sub-topic 6.3\\332"; 
/* (17) */ 


" Dummy sub-topic 7\\335" 


); 
data "НЕР" C1, "intro", purgeable) ( 

This demo program is used to demonstrate the multi-topic 
on-line help function. As many as 100 distinct help topics can 
exist. (This is adjustable by changing the value in: “8define 
MAX-HELP 100” in help.c) 

Use ResEdit to create the HELP resources Cthey'/re just 
simple ASCII text), or write your own program to create them. 

Feel free to use this code in your applications. I’d 
appreciate comments. 

William Rausch 

Battelle, Pacific Northwest Labs 
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Math/ 1406 

Battelle Blvd. 

Richland, WA 99352 
589-375-2249 


data ‘HELP’ (100, purgeable) ( 
These are just some words. 


date "НЕР" (101, purgeable) ( 
These are just some words to take space up so that the 
scroll bar will operate. 


); 
data 'HELP' (4, "stillmore", purgeable) ( 

The help dialog contains an OK button and two boxes, one 
for the list of topics end one to show the help information 
for the currently selected topic. The function builds the list 
of topics dynamically, using а STR® resource number passed to 
it by the calling routine. 

Each string іп the STR* resouce contains а topic and a 
reference number. The reference number is the ID of а HELP 
resource. Whenever the user selects & topic, the ASCII text 
from the corresponding HELP resource is displayed in this 
scrollable TextEdit record. 


; 
data 'HELP' (200, purgeeble) ( 
MacTutor™ is а great magazine for Macintosh programmers. 


date 'HELP' (201, purgeable) ( 
Not much here. This must be а dull topic. 


date ‘HELP’ (300, purgeable) ( 
This will be a HELP resource someday. 


); 
data 'HELP' (7, "morehelp", purgeable) ( 

It is very easy to create the HELP resources using ResEdit 
from Apple Computer. The version I used is “1.1 minus D^. The 
biggest improvement I've noticed is that now you can edit 
unknown resources as hex or ASCII. To create this resource, I 
just typed into the ASCII portion of the window. 

I've also used ап editor and ResEdit together in Switcher 
end that works OK too. Set the editor to eutowrep though, 
beceuse you don't want extreneous carriage returns in your 
HELP resource. Desk Accessory editors work well also. 


data 'HELP' (500, purgeable) ( 
I don’t have much to say here. 


data ‘HELP’ (333, purgeable) ( 
Note that any printing characters can be used: *£joffS. 


7 
data 'HELP' (332, purgeable) ( 
This particuler HELP resource is referenced by several 
different topics. In many cases this can be a useful feature, 
as many key words may apply to the same concept. 


data 'HELP' (334, purgeable) ( 
This is number 334. 


date 'HELP' (400, purgeeble) ( 
This is number 400. 


); 
date ‘HELP’ (335, purgeable) ( 
The very last one is this one for topic seven. oer 


7 Sau 


GEE. 
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ABC's of C 


Stars! The reason we have stars this 
month is because Jane, the seven year old é 
who hangs out around here, wanted them. | 
We also have triangles, pentagons, hexa- 
gons,anda large H-like thing. The pointof 
all this was to use QuickDraw functions to 
draw polygons and regions. These func- 
tions were integrated into the program two 
columns back so we now have one func- 
tion that can draw rectangles, rounded 
rectangles, arcs, ovals, lines, polygons, 
and regions. The program is fairly straight 
forward, but it took a while to get it to work 
correctly. At this point, our program is a 
fairly complex, and complete implemen- 
tation of some of the more advanced fea- 
tures of quickdraw. The major operations 
of quickdraw are supported including 
Frame, Paint, Erase and Invert. The only 
one missing is Fill. Implementing these 


functions for polygons and regions extends the program to the 
most general quickdraw constructions. The next level of com- 
plexity would be to implement pictures. Figure 1 shows some of 
the paint type drawings we can construct. 

We have also improved on our Mac user interface design. 
We now support desk accessories. Since this opens up the 
possibility of having a second window obscure our drawing, we 
also have to implement update events to restore the drawing after 
aDA hascovered partof our window. So weneed an update event 
as well. Since our program draws directly to the screen, what we 
have is a kind of MacPaint approach, where even though our 
quickdraw objects are generalized polygons and regions, after 
they are drawn, our screen is simply a bit map. This lends itself 
to an obvious approach for update events: simply copy the 
window to an off-screen bit map and then use copybits to update 
the window. This is the approach we have used this month. Other 
improvements to the user interface might be to made our window 
growable and to add multi-window capability. Improvements to 
our "paint" program would be to make it into a "draw" program 
where each object on the screen retains it's "object-oriented" 
nature rather than becoming a bit map. This would also require 
a more complex update function to re-draw the screen from the 
object definitions, rather than from the saved bip map image. We 
will look at this approach next month as we generalize our 
quickdraw objects even further. 

C Review 

One of the most confusing things about C is the use of 

pointers and handles from a Pascal machine definition. Let us try 
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Polygons and Regions as Quickdraw Objects 


File Edit Shape 


Bob Gordon 
Contributing Editor 
Minneapolis, MN 
MacTutor Vol. 3 No. 5 


Operation 


Fig. 1 Polygons & Regions in this month's paint program 


to review how this is done. Suppose we have an event record 
declared as theEventand we wish to pass this to a subroutine. This 
is normally done by passing the address of the event record 
structure by using the & function. Hence, we might do something 
likeFoo(&theEvent). This would pass the address of theEvent to the 
routine Foo. Now what do we do in Foo? The answer is we 
prepare the variable with which we accept this address: 


Foo(myEvent) 

Event Record — *myEvent; 

Whatthis means is thatnyEvent is a pointer to anevent record 
and it is this address that is being passed to Foo; *myEvent is the 
actual event record, dereferenced from nyEvent. Hence through- 
out Foo, we are using the pointer to our event record. This means 
it must be dereferenced first before being used to access fields of 
myEvent. There are two ways to do this in C: 


point = (*nyEvent) . where; 
point = myEvent-»where; 


The same approach extends to handles as the next example 
shows: 


rect = (**teRecHandle).viewRect; 
rect = (*teRecHandle)->viewRect; 


Notice that if we try to use something like 
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point = myEvent . where; 


within Foo, the Lightspeed compiler will return a message 
saying that "where" is not a field of myEvent. This is because 
nyEvent is a pointer to theEvent, not our event record structure 
itself. 

This is futher complicated by situations where we must pass 
the data structure itself, and not a pointer to it. Normally this is 
notallowed in C. However, "Macinized" C compilers allow us to 
pass the actual data by calling Foo( theEvent) instead of calling 
Foo(&theEvent). This often leads to another problem in C. When 
calling routines that modify the variables passed to it as VAR 
variables, we must pass the address of the variable as in 
"&theEvent", rather than simply "theEvent". This often leads to 
compiler errors when we fail to insert the required & for a VAR 
parameter. In pascal, the programmer does not need a different 
syntax for VAR values so you don't have to pay much attention 
to which parameters are VAR's and which are not. When you 
have this error, you'll get a message that says something like 
wrong size for a pascal variable. This is a clue that the & is 
missing in the call. An example of this is the SetPort and GetPort 
trap calls which are defined as: 


SetPortCgp) 
GrafPtr gp; 


GetPort(gp) 
GrafPtr *gp; 


Now when we call these routines, for SetPort we pass the 
window pointer for our window as in: 


SetPortCnyW indowPtr); 


But when we call GetPort to save the current port in a 
temporary window pointer, we pass the address of our variable 
as in the following because it is a VAR parameter: 


GetPortC&myTempPtr); 


For some reason, very few C books, even the Macintosh 
ones, do not fully explain pointers and handles in C in relation to 
pointers and handles in Pascal, from which all the toolbox trap 
calls are defined. For more on this subject, and on memory 
management, see chapter six on memory management in our 
book, Using the Macintosh Toolbox with C by Sybex, which we 
are more or less following in this series. 

Polygons 

My first idea for polygons was to develop a function that 
would collect points for a polygon on the fly. After selecting 
"Open Poly" from a menu, you would use the mouse to place 
points on the screen, lines would connect them, and after select- 
ing "Close Poly," you could reproduce the new polygon at will 
with the all purpose drawing function, that is the central feature 
of our program. I got part of it written when I discovered that it 
would not work: I kept getting some bomb. I think this happened 
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because after a polygon is opened it collects all line drawing 
information until the polygon is closed. This apparently includes 
such things as the lines involved in menus so doing almost 
anything created a multitude of lines. I did not investigate 
further, but decided to simply create some new shapes (the 
aforementioned pentagons, hexagons, and stars) that we could 
draw. This may imply that a pallette of drawing commands, 
maintained by the list manager would be more appropriate. This 
would be another possible design improvement in our program 
that could be pursued. (Gee, no wonder Mac programming never 
ends. The number of things you can add or improve on seems 
endless!) 

Creating the new shapes was relatively straight forward. I 
simply picked an arbitrary rectangle to work in and computed 
where the end points should be on pencil and paper. Then it was 
asimple matter to use lineto() functions to connect the dots. You 
will notice that the star is drawn the way you learned as a child 
(Jane has a lot of influence around here). To draw a star that 
would be completely filled in (by the paint operation), we would 
have to have ten points and do lineto's to describe the edges. 
Another opportunity for you to modify our program! 

It was after I had built the first "make polygon" routine that 
I ran into my second problem. I installed the various polygon 
drawing verbs into the all purpose draw function [see the dr.c 
code listing and the drDraw routine] and ran the program. As 
soon as tried to do anything with a polygon I gota divide by zero 
error. I traced the problem to a call to MapPoly(). MapPoly() is 
a QuickDraw function that scales a polygon from one rectangle 
to another. In the process it changes the size and aspect ratio of 
the polygon. Just what we need to control the size and aspect of 
the polygon with the mouse. Unhappily it didn't work. It seems 
the source and destination rectangle need to differ slightly. 
Inseting the source rectangle solved the problem. Another ap- 
proach you can try, and which I played around with, is writing yur 
own MapPoly() function. There is another QuickDraw function 
called MapPt( which does the same scaling operation on a point. 
It is a relatively simple task to build a function that maps all the 
points in a polygon. The only hitch was in knowing what a 
polygon looks like. 

According to Inside Macintosh, a polygon looks like: 


struct Polygon 


short polySize; 
Rect polyBBox; 
Point polyPoints[]; 


) 


The array polyPoints is variable length. polySize specifies 
the total length of the polygon (in bytes) including the space 
needed to hold polySize and polyBBox (10 bytes). By stepping 
through the array and calling MapPt on all the points, we can re- 
create the MapPoly function. The problem with MapPoly() 
apparently has to do with the source rectangle. I was using the 
polyBBox as the source. By copying polyBBox to another 
rectangle and Inseting it to make it one point larger or smaller all 
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around, eliminates the problem. Now, I don't know if there is a 
better way to do this, and I have not gone in with a debugger to 
see what is actually going on, so any thoughts in this area will be 
appreciated. 

Regions 

Regions are one of the more amazing capabilities built into 
QuickDraw. This program only introduces them. I am going to 
ignore all the things one can do with regions and simply focus on 
getting a region on the screen. 

Bascially,Ihad the same problems with regions as I did with 
polygons. The function MapRgn() caused a divide by zero error 
(I only solved the polygon problem after I solved it for regions), 
and I decided I did not want to write а MapRgn(. A region looks 
like: 


struct Region 


short rgnSize; 
Rect rgnBBox ; 
/* optional region definition data */ 


) 


Unlike a polygon, there is not a hint of what is inside a 
region. 

The region included in the program is very simple-it is 
made of three rectangles. (It could have easily been a polygon. 
The reason it looks like an "H" is because I wanted to write 
"HELLO" in REALLY BIG LETTERS. Some other time.) A 
region (the optional region definition data) is a series of horizon- 
tal slices of the object. Each slice starts with the y-coordinate 
followed by a series of x-coordinates and terminates with a 
32767. After the last slice is another 32767. The x-coordinates 
turn the pen on and off so that drawing starts at the first one 
continues to the second, is off to the third, and on to the fourth, 
etc. The region defined in the program looks like: 


6 9 10 40 
90 32767 
25 10 40 
35 10 40 32767 
60 0 10 40 

90 3276732767 


A region can be quite large. Try replacing the FrameRect() 
calls in makeregion() with FrameRoundRect() or FrameOval() 
and see what happens. In any case, we never have to deal with 
the inside of the region structure because QuickDraw provides all 
sorts of routines for manipulating them. 

As with the polygons, the capabilities to draw regions with 
all the drawing operations have been added to the general 
purpose drawing routine. 

Some Comments on the Program 

The functions that handle regions and polygons (e.g. 
fr poly( and fr герп()) do not operate on the originals. Instead 
they operate on a copy of the polygon (or region). This was to 
avoid possible problems of distortion because the mouse drawing 
routine starts with a two-by-two rectangle (I never tried it without 
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the copy, however). Since only one polygon is active at a time, 
there is a single temporary polygon space. The size of this space 
is by a call to setpolytemp() in each of the four make-polygon 
functions. setpolytemp() receives the size of the new polygon as 
aparameter and creates a handle to a polygon if it was not already 
created. On subsequent calls setpolytemp() compares the 
received size with the size it already has and makes the polytemp 
size larger if necessary. This way the space needed to make a 
copy of the largest (in bytes) polygon is readily available. The 
region is different. There is a QuickDraw function, CopyRgn() 
that copies a region. It handles the memory allocation. 

The region and polygons are created during drinit() which 
is called once at the beginning of the program. 

Since there is only one set of polygon (and region) drawing 
verbs, there needed to be away to specify which polygon to use. 
A selection from the shape menu ends up calling drshape() where 
the polygon based shapes are all changed into polygons and the 
correctone to use is placed in the global polycurrent. The various 
polygon functions use polycurrent as the original polygon. 


A Bug 

When drawing the polygon shapes (star, pentagon, etc.) 
there was sometimes a dot left where the mouse button is first 
pressed. Obviously I was not erasing it correctly, and it took 
some time to figure it out. Finally, the problem was solved by 
carefully making both the starting and ending points even coor- 
dinates so the generalized draw function would not try to draw a 
single point polygon. I think the dot problem is solved for all the 
polygon structures but if not, study the initialization of the draw 
fuunction loop variables for a better answer. 


Update Events 

Figures 2 and 3 show that our program now supports desk 
accessories. We also must manage our menus to turn on and off 
the edit menu when a system window for a DA is active. This is 
done by calling a menu adjust type routine in our main loop. It can 
be tricky however to identify all the user possibilities for activat- 
ing one window over another so that the menus correctly reflect 
the state of the machine. The check menu routine does this 
function by checking all the possible combinations of having our 
window be on the screen and be the front window. If it is not on 
the screen, or on the screen and not the front window (must be 
behind a DA window) then our menus must look different. 

When weselectanew window, we also define an off-screen 
bitmap using the characteristics of our window. Both the window 
and the bit map are defined relative to screenBits.bounds. This 
quickdraw global defines the current screen size and by making 
all drawing relative to it, means our program will work on a 
Macintosh II or large screen addition, which use a different 
screen size than the present Macintosh. In our init routine, we set 
up our window related rectanges relative to screenBits.bounds to 
achieve this video independence. 

Study the new window routine to see how the bit map is 
allocated with NewPtr. When the window is closed, we release 
the pointer to the bit map as well so that the next New Window 
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call can create another off-screen bit map. Here are the new 
global declarations for our bit map: 


BitMap offMap; 
Rect copyRect; 
Rect drawRect; 


The new window code that creates the bit map is shown 
next: 
drawRect=(*theW indow).portRect; 
copyRect=drawRect; 
offMap.rowBytes = screenBits.rowBytes; 
mapBytes = of fMap.rowBytes*(screen.bottom-screen. top); 
of f Map .baseAddr=NewP tr CmapBytes ); 
of f Map .bounds=screen; 


CopyBi tsC&of f Map, &of f Map, &copyRect, &kcopyRect , srcXor ,Ni1); 


The number of bytes in arow also changes on the Macintosh 
II so again, we define the rowbytes field of our bit map by using 
the current screen device defined by quickdraw in 
screenBits.rowbytes. Since the screen resolution also changes, 
we determine the number of pixel lines from screenBits.bounds, 
which we have copied into the screen rectangle. The number of 
bytesto allocate for the bit map is then the bytes per row times the 
number of rows in the display, which we store as mapBytes. 

Once the bit map is created, we must then determine the 
most opportune moment to save the window contents and restore 
it from the bit map. The CopyBits function is used for this 
purpose. In our update event routine, we use CopyBits to blast the 
off-screen bit map back on screen in the portRect of our window. 
We do this whenever the update event is generated for our 
window. In particular, we do it when the new window function 
generates an update event to create our window. This led to the 
chicken and the egg problem of which comes first: the window 
or the saved bit map! The solution was to erase the bit map when 
it is first created so that the first update event for our window 
won't fill our window with a random display of memory in 
graphics form! Erasing our bit map is done by just doing a 
CopyBits on itself. 


doupdateCupdateW indow) 
WindowPtr updateWindow; 

( 

GrafPtr temp; 

GetPort(&temp); 

SetPortCupdateWindow); 

BeginUpdateCupdateWindow); 

if CCtheWindow) and CtheWindow=updateWindow 2) 

CopyBitsC&of fMap, &C*updateWindow).portBits, 
&copyRect, &drawRect , srcCopy, Nil); 

EndUpdateCupdateWindow); 

SetPortCtemp); 

) 


Once our update event was working, the next problem was 
to fine the opportune time to call our Save Window routine which 
does a CopyBits in the opposite direction, saving the portRect of 
our window to our bit map. This proved to be the hardest part of 
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all! The various interactions of the DA windows with our 
windows and the order in which activate and deactivate events 
are generated, and the manner in which the window manager 
draws and re-draws windows, all combined to make this a 
frustrating little problem. Since our program handles two events, 
a key down and a mouse down, this seem to be the obvious place 
to save the window. The key down event worked fine. When a 
key was pressed, the window was saved, then the key was 
processed. The mousedown was another story! I was continually 
having problems with the save window capturing the wrong set 
of pixels! The problem was finally solved by being more careful 
about when a mousedown event in the content region of our 
window shouldcall SelectWindow, which generates activate and 
udpate events for the window. 


Here is the save window routine, and the content event 
which calls it: 
Save indouwC) 


CopyB i tsC&C* theWindow).portBi ts, &of f Map, &drawRect, 
&copyRect, srcCopy, Nil); 


cese inContent: 
if (whichWindow equals theWindow) 


if CwhichWindow notequal FrontWindowC)) 


Calculator BEST UM 
3 Я88Е55888888886 80588868868; 


B: 
: 
i 
: 
RBY 
: 
: 
B 
ER 
HH 
: 


Фе 


Fig. 3 SelectWindow generates Update Event 
CopyBits restores our drawing. 


SelectWindowCwhichwWindow); 
else 
if (CursorInUseC) equals 2) 


drdrawCwhichWindow); 
SaveWindow(); 
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break; 


A Note from a Reader 

Kirk Kerekes of Tulsa OK provides some additional infor- 
mation on the surround functions used for the general purpose 
drawing routine. AsI mentioned when we started building these 
drawing routines, LightSpeed C does not allow us to take the 
address of Toolbox functions. Mr. Kerekes points out that in 
Lightspeed C, the stack based traps are handled with an automatic 
in-line exception; there is no "glue" function. Since there is no 
function, there is no address. We can use address passing with 
ToolBox traps, however by using GetTrapAddress() to retrieve 
the address of the trap and pass them using the CallPascal() 
function. This is described on page 9-7 of the LightSpeed 
manual. The following little program (courtesy of Mr. Kerekes) 
illustrates the technique. 


/* callpascal 
x 


* demonstrates use of CallPascal() 
* address passing in LightSpeed C 
x 


* By Kirk Kerekes 
* Cwith some additional comments by Bob Gordon) 
x 


*/ 


"include — "QuickDrew.h" 
*f include X "OSUtil.h" 
include X "Window.h" 


#def ine Nil OL 


pascal void CallPascal(); 


nainC) 


Rect testrect; 
Rect wrect; 
WindowPtr thewindow; 


InitGraf C&thePor t); 

InitWindowsC); 

InitFonts(); 

Ini tMenus( ); 

Ini tDialogs(Get TrapAddress(@xA9F 4)); 
/* AQF4 = ExitTo Shell */ 


SetRect(&wrect, 10, 10, 500, 300); 
thewindow = NewWindow (Nil, &wrect, "\pGetTrapAddress”, 
TRUE, 2, -1L, FALSE, Nil); 

SetPor t( thewindow); 

/* make a rectangle */ 
SetRect(&testrect, 20, 20, 100, 200); 

/* fill it with gray, the usual way */ 
FillRect(&testrect, gray); 

/* now make it smaller */ 
InsetRect(&testrect, 10, 10); 

/* fill it with black with the Trep Address 
technique. The addresses are listed in a 
table in Inside Macintosh. Note that by 
looking at the code you would have very 
little idea what this does. */ 

CallPascalC&testrect, black, GetTrepAddress(0xA845)); 


while C!Button()) 
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DisposeWindowCthewindow); 


) 


He points out that this technique does result in more obscure 
code. 

Final Comments 

I received a couple goodies in the mail over the last two 
months. The first was the new version of LightSpeed C. More 
on this next time, Ihope. The other was the Best of MacTutor. I 
especially recomend the C Workshop series by Bob Denny. 
Anyone who has come this far in ABC's of C should benefit from 
reading his columns. The Pascal Procedures column by Chris 
Derossi is also highly relevant to what is going on here. See his 
Introduction to QuickDraw (p. 228) and QuickDraw does Re- 
gions! on page 231. 

The other comment before presenting the program 
deals with where we go from here. We have been more or less 
following Using the Macintosh ToolBox with C. They will begin 
working on a text editor in a few chapters. Since the one thing I 
have heard from people is that they don't wish to see another text 
editor, I had wondered about what sort of project would be fun, 
useful, and illustratrative. Unless there are objections (or a better 
idea), I think we'll continue doing drawing. We may end up with 
some sort of mini MacDraw. 

Next time we'll return to quickdraw and try to draw poly- 
gons, regions, and pictures in a more general way so they retain 
their object oriented nature like MacDraw. 
js Quickdraw Example 


Compiled with LightspeedC 


Every place you see event-? where, 


x 

x 

х Important note for Мас C users: 

x 

x replace it with &event- where 
x 


/ 
include "abc.h" 
8include "Quickdrew.h" 
8include "EventMgr .h" 
*Üinclude "WindowMgr .h" 
8$include "MenuMgr .h" 
8$include "FontMgr .h" 


/* def ines for menu ID's */ 


def ine Mdesk 100 
#def ine Mfile 101 
def ine Medit 102 
"def ine Mshape 106 
"def ine Mop 107 
/* File */ 

def ine iNew 1 
“define iClose 2 
def ine iQuit 3 
/* Edit */ 

def ine iUndo 1 
gef ine iCut 3 
#деѓ ine iCopy 4 
def ine iPeste 5 
def ine iClear 6 
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/* Global variables */ 


MenuHandle menuDesk;  /* menu handles */ 
MenuHandle nenuF ile; 
MenuHandle menuEdit; 
MenuHandle menuShape ; 
MenuHand le menuOp ; 
WindowP tr theWindow; 
WindowRecord windowRec; 
Rect dragbound; 
Rect screen; 
Rect boundsRect; 
BitMap of f Map; 
Rect copyRect ; 
Rect drewRect; 
pd 


initsysQ); /* system initialization */ 
initepp(2; /* application initialization */ 
event loop(); 


crashC) 


ExitToShe11C2; /* we are dead folks */ 


/* system initialization */ 
initsys¢) 


InitGraf(C&thePort); 
InitFonts(); 

Ini tWindows(); 

Ini tMenus(); 
TEInitC2; 
InitDialogsC&crash); 
InitCursor(); 
FlushEventsCeveryEvent, 2); 


/* these two lines done */ 
/* automatically by Mac C */ 


theWindow = Nil; /*indicates no window */ 
screen=screenBi ts . bounds; 
SetRect(&dragbound, screen. lef t*4, screen. topt24, 
screen.right-4,screen.bottom-4); 
SetRectC&boundsRect,screen. lef t*30, screen. top*50, 
screen.right-38, screen .bottom-50); 


/* 
* application initialization 
x 


i 


se tupmenuC ); 
drinit(); 


а. 


menuDesk = NewMenuCMdesk,CtoPstr С "\24" )); 
AddResMenu (menuDesk, 'DRVR'); 
InsertMenu (menuDesk, 0); 


menuFile = NewMenu(Mfile, CtoPstr("File")); 
AppendMenu (menuFile,CtoPstr(C"New/N; Close; Quit/Q")); 
InsertMenu (menuFile, 0); 


menuEdit = NewMenuCMedit, CtoPstrC"Edit")); 

AppendMenu (menuEdit, CtoPstr("Undo/Z;(-;Cut/X;Copy/C; Paste/ 
V;Clear" )); 

InsertMenu (menuEdit, 0); 
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menuShape = NewMenu(Mshape, CtoPstr(C"Shape")); 
AppendMenu (menuShape, CtoPstr("Line;Rectangle; Oval; 


Round Rectangle;Arc")); ` 


AppendMenuCmenuShepe , CtoPstr C" Tr iangle;Pentagon; 


Hexagon ; Pentagram" )), 


AppendMenu (menuShape, CtoPstrC"Region" 22; 
InsertMenu (menuShape, 0); 


menu0p = NewMenu(Mop, CtoPstr("Operation")); 

AppendMenu (menu0p, CtoPstr("Frame;Paint; Erase; Invert")); 
InsertMenu (menuOp, 0); 

y UNES 


/* 


x 


*/ 


Event Loop 
Loop forever until Quit 


eventloopC) 


EventRecord 


theEvent; 


cher с; 


пыш 


SystenTaskC); 
CheckMenusC ); 
if (GetNextEventCeveryEvent, &theEvent 2) 


) 
) 


/* 
x 
x 


switch( theEvent .what) 
( /* only check key end */ 
case keyDown: /* mouse down events */ 
if CCtheWindow) and CtheWindow equals FrontWindow()) 2 
SaveWindow(); 
C = theEvent.message & charCodeMask; 
if CtheEvent.modifiers & cmdKey) 
domenuCMenuKeyCc)); 
else if CtheWindow) 
SysBeep(5); 
break; 
case mouseDown: 
domousedown(& theEvent); 
break; 
cese updateEvt: 
doupdateCCW indowP tr )theEvent .message); 
break; 
case activateEvt: 
doactivate(&theEvent); 
break; 
default: 
break; 


CheckMenus 
Update menu bar if window active 


ашады 


if A ERES and CtheWindow equals FrontWindowC22) 


EnableItem(nenuF ile, iClose); 
DisebleItem(menuF ile, iNew); 
DisebleItem(menuEdit,9); 
EnableItem(nenuShepe , 9); 
EnebleItemC(nenuOp, 0); 
шы ene 


else 


( 
if CCtheWindow) and CtheWindow notequal FrontWindow())) 


DisebleItemCnenuF ile, iNew); 
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DisebleItem(menuF ile, iClose); 
EnebleItem(menuEdit,92); 
DisebleItemC(menuShepe,2); 
ынаны ды 


else 


if CCtheWindow equals Nil) and CFrontWindowC) equals 


М1122 


EnebleItem(menuF i le, iNew); 
DisableI temCmenuF ile, iClose); 
Disablel temCmenuEdit,@); 
DisableI temCmenuShape, 2); 
poe een Mot 


else 


EnableItem(menuF ile, iNew); 
DisebleItemCmenuF ile, iC lose); 
EnebleItemCmenuEdit,02; 
DisebleItemCmenuShape, 0); 
DisebleItemCmenuOp, 9); 


) 
) 
) 
) 


/* off screen bitmap */ 
Save indowC) 


CopyBitsC&C*theWindow).portBits, &of f Map, &drawRect, 
&copyRect , srcCopy, Nil); 


/* domousedown 


* handle mouse down events 
x 


domousedownCer) 
EventRecord *er ; 


short windowcode; 

WindowPtr whichWindow; 

short ingo; 

windowcode = FindWindowCer- where, &whichWindow); 


switch Cwindowcode ) 


case inDesk: 
if CtheWindow notequal 9) 


ае False); 


break ; 
case inMenuBar: 


if CCtheWindow) and CtheWindow equals FrontWindow( ))) 


SaveW indow( ); 
domenuCMenuSe lect Cer-> where )); 
break; 

case inSysWindow: 
SystemC lickCer, whichWindow); 
break; 

case inContent: 
if аны equals theWindow) 


if CwhichWindow notequal FrontWindow( )) 
SelectWindow(whichWindow); 

else 

if (CursorInUseC) equals 2) 


drdrewCwhichWindow); 
SaveWindow(); 
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) 
) 
break; 
case inDrag: 
DragW indowCwhichWindow,er->»where, &dragbound); 
break; 
case inGoAway: 
ingo = TreckGoAway(whichWindow, er-? where); 
if Cingo) 


CloseW indowCwhichWindow); 
dd = Nil; 


break; 
default: 
break; 


) 


doupdateCupdateW indow) 
WindowPtr updateWindow; 


( 
GrafPtr temp; 


GetPort(&temp ); 

SetPortCupdeteWindow); 

BeginUpdate(CupdateW indow); 

if CCtheWindow) and CtheWindow-updeteWindow 22 

CopyB itsC&of f Map, &C*updeteWindow).portBits, 
&copyRect , &drawRect, srcCopy, Nil); 

EndUpdateCupdateW indow); 

и 


doactivateCer) 
EventRecord *ег; 


WindowPtr  eventwindow; 


eventwindow=(W indowP tr )Cer-> message); 
if Cer-»modif iers & activeF lag) 


else /% deactivate */ 


( 
) 
) 
/* domenu 
x hendles menu activity 
* simply а dispatcher for each 
x menu. 
*/ 
domenuCac) 
( long mc; /* menu result */ 
short menuId; 
short menui tem; 
char daName [64]; 
GrafPtr temp; 
short accI tem; 


menuld = HiWord(mc); 
menuitem = LoWord(mc); 


dics (nenuId) 


case Mdesk : ( 
GetI temCmenuDesk , menui tem, daName ); 
GetPortCtemp?; 
acc! tem=OpenDeskAcc(daName ); 
SetPort( temp); 
break ; 
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cese Mfile : dofileCmenuitem); 


break; 


case Medit :( 


if Cnot SystemEdi tCmenui tem-1)) 
break ; 


case Mshape: doshape(menui tem); 


break; 
case Mop: dooper (menuitem); 
break ; 
default: 
break; 
HiliteMenuC0); 
) 
doshapeCiten) 
short item; 


( 
static short — lestitem = 9; 


CheckItem (menuShepe, lastitem,False); 
CheckI tem CmenuShape, item, True); 
lastitem = item; 

тше, 


dooperCiten) 
short item; 


static short lastitem = 0; 


CheckI tem Cmenu0p, lastitem,False); 
CheckI tem (menuOp, item, True); 
iia = item); 


/* dofile 


x 
*/ 


dofileCiten) 
short 


char 
Tong 


handles file menu 


item; 


*titlel; /* first title for window */ 


nepBytes; 


шз (iten) 


cese iNew : /* open the window */ 


case iClose : 


title! = "ABC Window"; 


theWindow = NewWindowC&windowRec, &boundsRect, 
CtoPstrCtitle1),True,noGrowDocProc, 


(WindowPtr) -1, True, 0); 
PtoCstr(titlel); 


drawRect=(*theW indow).por tRect; 
copyRect=drawRect; 


offMap .rowBytes = screenBits.rowBytes; 
mapBytes = of fMap.rowBytes*(screen.bottom-screen. top); 


of f Map .baseAddr=NewP tr (mapBytes ); 

of f Map .bounds=screen; 

CopyBi tsC&of fMap, &of f Map, &copyRect, 
&copyRect,srcXor , Nil); 

break; 


CloseW indow( theW indow); 
DisposP tr Cof f Map .baseAddr ); 
theWindow = Nil; 

break; 


case iQuit : /* Quit */ 


ExitToShe11C); 
break; 
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/* close the window */ 


default: 
break; 


/* 
* dr.c 
x 


* drewing routines 
*/ 


®include “abc.h" 
Sinclude “quickdraw.h” 
®include “windowMgr .h" 


struct shapes 


short kind; 
Rect size; 
short oper; 


д 


struct shapes — shepal20]; 


short shapdx; 
PolyHendle triangle; 
PolyHandle pentagon; 
PolyHandle hexagon; 
PolyHandle pentagram; 
RgnHandle theregion; 
RgnHendle tempregion; 
PolyHendle polytemp = £; 
PolyHandle polycurrent; 
short phpts; 

/* 


* Quickdraw surround functions. 

* These functions provide а consistent 

* interface Cat some loss of generality) to 
* all the quickdraw drawing functions. 

*/ 


/* FRAMING */ 


fr-polyCstertpt,endpt) 
Point startpt, endpt; 


Rect drt; 
Rect srt; 


Pt2Rect(startpt,endpt,&drt?; 
BlockMoveC&C*polycurrent2?-?polyBBox, &srt,sizeof (Rect)); 
BlockMove(*polycurrent, *polytemp, (*polycurrent)-»polySize); 
InsetRect(&srt, -1, -1); 

MapPoly(polytemp,&srt, &drt); 

И 


fr.regnCstartpt, endpt) 
Point startpt, endpt; 


Rect rtl 


CopyRgn( theregion, tempregion); 
BlockMove(&(*tempregion)-»rgnBBox, &r1,sizeof(Rect)); 
InsetRectC&r 1, - 1, - 15; 

Pt2Rect(startpt, endpt,&r); 


MapRgnCtempregion, ігі, іг); 
Шаш tempregion); 


fr-lineCstartpt,endpt) 
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Point startpt,endpt; 


MoveTo(startpt.h,startpt.v); 
i al ex 


fr.rectCstertpt,endpt) 
Point  stertpt,endpt; 


Rect rt; 


Pt2Rect(startpt,endpt, &rt); 
бы а. 


fr-ovalCstartpt,endpt) 
Point startpt,endpt; 


Rect rt; 


Pt2Rect(startpt,endpt,&rt); 
EI 


fr-rortCstartpt,endpt) 
Point startpt,endpt; 


Rect rt; 


Pt2Rect(stertpt,endpt,&rt); 
тоннын a 


fr.arc(startpt, endpt) 
Point startpt,endpt; 
Rect rt; 
Rect trt; 
short se; 
short агага, 


Pt2Rect(stertpt,endpt,&rt); 
cp-arc(art, &trt, ка, &aa); 
FrameArc C&trt,sa, aa); 


/* ERASING */ 


er_lineCstartpt, endpt) 
Point startpt,endpt; 


GrafPtr ор; 
Pettern tpet; 


GetPor tC&gp ); 
BlockMoveCgp->pnPat, &tpat, 8); 
PenPat(gp-> bkPat); 
MoveToCstartpt.h,startpt.v2; 
LineToCendpt .h, endpt . v); 
айы 


er.polyCstertpt,endpt) 
Point startpt, endpt; 


Rect drt; 
Rect srt; 


Pt2Rect(star tpt, endpt,&drt); 


BlockMoveC*polycurrent , *polytemp, (*polycurrent)->polySize); 


BlockMoveC&C*polycurrent )-? polyBBox, &srt, sizeof (Rect)); 
InsetRect(&srt, -1, -1); 
MapPoly(polytemp, &srt, &drt); 
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ees 

er.regn(stertpt, endpt) 
Point startpt, endpt; 
Rect ror 


CopyRgn( theregion, tempregion); 


BlockMove(&(*tempregion)->rgnBBox, &r1,sizeof (Rect); 


InsetRect(&r1,-1,-1); 
Pt2Rect(startpt, endpt, &r); 
MapRgn(tempregion, ігі, ёг); 
іш ыы ыы 


er_rect(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 


Pt2Rect(startpt, endpt, &rt); 
ыы 


er-ovalCstertpt,endpt) 
Point stertpt,endpt; 


Rect rt; 


Pt2Rect(startpt, endpt, &rt); 
наны 


er.rort(startpt,endpt) 
Point startpt,endpt; 


Rect rt; 


Pt2Rect(startpt,endpt, &rt2; 
Acn а C 


er_arc(startpt, endpt) 
Point startpt,endpt; 


Rect rt; 
Rect trt; 
short sa; 
short ав; 


Pt2Rect(startpt, endpt, &rt); 
cp-arcC&rt , &trt, &sa, баа); 
das C&trt,sa,aad; 


/* PAINTING */ 


pt.lineCstartpt, endpt) 
Point startpt,endpt; 


GrefPtr 9p; 
Pattern tpat; 


MoveTo(startpt.h,startpt.v); 
ai ыны 


керо шаар ерер) 
Point startpt, endpt; 


Rect drt; 
Rect srt; 
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. Pt2Rect(startpt, endpt, &drt); LineToCendpt .h, endpt .v2; 
BlockMoveC*polycurrent, *polytemp, C*polycurrent)-?polySize2; PenMode( tpnMode); 

BlockMoveC&C*polycurrent )-? polyBBox, &srt, sizeof (Rect)); ) 

InsetRect(&srt, -1, -1); 


MapPoly(polytemp, &srt, &drt); in.rect(startpt, endpt) 
шыны. Point startpt,endpt; 
Rect rt; 

pt_regn(startpt, endpt) 

Point startpt, endpt; Pt2Rect(startpt, endpt,&rt); 

InvertRectC&rt); 

Rect г, ri; ) 
CopyRgnCtheregion, tempregion); in-polyCstartpt, endpt) 
BlockMoveC&C*tempregion)-»rgnBBox, &ri,sizeof (Весі) ); Point startpt, endpt; 
InsetRect(&r 1, -1, - 12; ( 
Pt2Rect(startpt, endpt,&r); Rect drt; 
MepRgnCtempregion, &ri, ёг); Rect srt; 


PaintRgnCtempregion); 
) Pt2Rect(startpt, endpt, &drt); 
BlockMoveC*polycurrent, *polytemp, (*polycurrent)-»polySize); 


pt_rect(startpt, endpt) sr t=(*po lytemp )-> po 1lyBBox; 
Point startpt,endpt; InsetRect(&srt, 1, 1); 
MapPoly(polytemp, &srt, &dr t); 
Rect rt; тады 
Pt2Rect(startpt,endpt,&rt); 
PaintRect(&rt); in-regnCstertpt, endpt) 
) Point startpt, endpt; 


pt-ovalCstartpt,endpt) Rect г, rl; 
Point startpt,endpt; 
CopyRgnCtheregion, tempregion); 


Rect rt; BlockMove(&(*tempregion)->rgnBBox, &r1,sizeofCRect)); 
InsetRect(&r1,-1,-1); 
Pt2Rect(startpt,endpt,&rt); Pt2Rect(startpt, endpt,&r); 
наны MapRgnCtempregion, %гі, іг); 


шыдан ыы 


pt-rort(startpt,endpt) 
Point startpt,endpt; in-ovalCstartpt,endpt) 
Point startpt,endpt; 


Rect rt; 
Rect rt; 
Pt2Rect(star tpt, endpt,&rt); 
PaintRoundRect(&r +, 28, 28); Pt2Rect(startpt, endpt,&rt); 
) ыы” 
pt-arcCstartpt,endpt) in-rortCstartpt,endpt) 
Point startpt,endpt; Point startpt,endpt; 
Rect rt; Rect rt; 
Rect trt; 
short sa; Pt2Rect(startpt, endpt, &rt); 
short аа; ВЕНИ 
Pt2Rect(startpt,endpt,&rt); 
cp-arcC&rt,&trt,&sa,&a8); in-erc(startpt,endpt) 
I E (&trt,sa,88); Point startpt,endpt; 
Rect rt; 
/* INVERTING */ Rect trt; 
short sa; 
in-lineCstartpt,endpt) short да, 
Point startpt,endpt; 
Pt2Rect(startpt, endpt, &rt); 
GrafPtr 9p; cp-arcC&rt,&trt,&sa, &aa); 
short tpnMode; InvertArc (&trt,sa, aa); 
GetPor t(&gp ); 
tpnMode = gp-?pnMode; 
PenMode(patXor ); /* ARC COMPUTATION 
MoveTo(startpt.h,startpt.v); * The arc is fixed at 90 degrees. This 


108 © The Essential MacTutor, Vol. 3 


* function Cused in all the arc functions 
* above) computes the correct rectangle, 
* start angle, апа arc angle given the 

Ж input rectangle Cand 90 degrees). 
x 
x 
x 


This makes drawing the arcs consistent 
with drawing the other shapes. 


*/ 
cp-arcCirt,ort,startangle,arcangle) 
Rect ігі; 
Rect “ог; 


short  *startengle; 
short *arcangle; 


short dh; 
short dv; 
static Point anchor; 


= ігі-әгідһі - irt-> left; 
dv = irt- bottom - irt->top; 
Ld (dh | dv)) 


anchor.v = irt->top; 
anchor .h = irt-> left; 


*ort = *irt; 


if Cirt-> left equals anchor .h) 
if Cirt-»> {ор < anchor .v) 


ort-> left -= dh; 
ort— top -= dv; 
*startangle = 180; 
яи = -90; 


е1ѕе 


ort-> left -= dh; 
ort-»bottom += dv; 
*startangle = 0; 
isa = 90; 


else 
if Rud < enchor.v) 


ort- top -= dv; 
ort- right += dh; 
*startangle = 180; 
*arcangle = 90; 


else 
ort right += dh; 
ort-»bottom += dv; 


*startengle = 0; 
Xarcangle = - 90; 


typedef short — C*drfunc2C2; 
drfunc а[][7] = 


(fr_line, fr_rect, fr_oval,fr_rort,fr_arc, 


fr-poly,fr.regn, 

pt-line,pt.rect,pt oval,pt rort,pt arc, pt. poly,pt regn, 
er line,er.rect,er oval,er .rort,er.arc, er. poly,er.regn, 
in line, in.rect, in oval, in .rort, in. arc, in_poly, in regn) ; 


/* INITIALIZE DRAWING 

* [nit all kinds in shape array (not used 
* yet and make polygons 

*/ 
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dion 
short i; 
for Ci = 0; i < 20; shepalitt*].kind = 0); 


shapdx = £; 
maketriangle(); 
makepentagon(); 
makehexagon( ); 
makepentagram( ); 
nakeregionC); 


) 


/* SET SHAPE 

* This sets the shape code to use 

* and sets it in the current shape 

* entry Conly one is used so far). 

* [n the case of polygons, it trenslates 
* the shape code to the polygon code and 
* sets the polygon to use in the 

* global, polycurrent. 


drshepeCcode) 
Short code; 


idu (code) 


case 6: 
polycurrent = triangle; 
break; 

cese 7: 
polycurrent = pentagon; 
code = 6; 
break; 

case 8: 
polycurrent = hexagon; 
code = 6; 
break; 

case 9: 
polycurrent = pentagram; 
code = 6; 
break; 

case 19: 
code = 7; 
break; 


shepa[shepdx].kind = code; 


/* SET OPERATION 

* Sets operation in shape array 
ж (only one used). Also sets 
* cursor to use. 


%/ 

droper (code) 
short code; 
shapalshapdx] .oper = code; 
Cursor ToUse(2); 

drdraw(w) 

WindowRecord “и; 
Point startpt; 
Point thispt; 
Point endpt; 
Point lastpt; 
Rect thisrt; 
Rect lestrt; 
GrafPtr port; 
drfunc frame; 
drfunc draw; 
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— 
x и и и MH »* и и и * 


— 


short engle; 


short dv,dh; 
Point Sp; 
Point tp; 
Point 1р; 
short shapx; 
short operx; 
short X; 
short у; 
SetPortCCGrafPtr2w); 
PenMode(patXor); 
PenPat(gray); 


shapx = shepa[shapdx].kind - 1; 

operx = shepa[shapdx].oper - 1; 

if ССѕһарх < 0) ог Coperx < 00) 
return; 


frame = а(0 ][shepx]; 


GetMouse(&startpt); 

x=startpt.h; 

y=startpt.v; 

if (х%2 notequal 8) 
x=x+1; 

if Cy%2 notequal 0) 
y-y* 1; 

stertpt.hzx; 

stertpt.vsy; 

lastpt=star tpt; 


do { 
GetMouse(&endpt ); 


x=endpt .h; 

y=endpt.v; 

if (x2 notequal 0) 
х=х+ 1; 

if Cy%2 notequal 0) 
у=у+ 1; 

endpt .h=x; 

endpt.v=y; 


thispt = endpt; 
LocalToGlobal(&endpt ); 


if K(PtInRgnCendpt,w-?contRgn) and 


not EqualPtCthispt, lastpt)) 


if Knot EqualPt(startpt, lastpt)) 


C*frame (startpt, lastpt); 
(*frame)Cstartpt, thispt); 
p = thispt; 


) 
while (Stil1Down()); 


(*frame)(startpt, thispt); 
PenMode(patCopy); 
PenPat(black); 
(*draw)(startpt, thispt); 


Make New Shapes 


These routines define polygons that 
ere available from the menu. Each 
simply defines a polygon Cassigning 
it to the global variable of the 
appropriate name). 

NO ERROR CHECKING IS DONE ON THE 
MEMORY OPERATIONS. 
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= /* get address of frame func */ 
drew = e[operxl[shepx], /* get addr shape/oper func */ 


еи: 


) 


short err; 


triangle = OpenPoly(C); 
МоуеТ0(20,20); 

(ілпе(20,0); 

LineC- 10, -20); 

LineC- 10,20); 

ClosePolyC); 

setpolytenpCC*tr iangle)->polySize); 


Coe 


) 


pentagon = OpenPoly(); 
МоуеТ0(50,0); 

Line(48,35); 

LineC- 19,65); 

LíneC-58,0); 

LineC- 19, -65); 

Line(48, -35); 

ClosePoly(); 
setpolytemp((*pentagon)->polySize); 


ee 


) 


hexagon = OpenPoly(); 

MoveTo (21,0); 

Line(58,8); 

Line(28,59); 

Line(-28,50); 

Line(-58,9); 

Line(-28,-59); 

Line(28, -50); 

ClosePoly(); 
setpolytemp((*hexagon)-) polySize); 


кера) 


ч 
ж” 


+ 26 A 0 м w и и М 


*/ 


pentagram = OpenPoly(); 
МоуеТ0(50,09; 

Line(38, 98); 

Line(-78, -55); 

Line(96,0); 

Line(-78, 55); 

LineC30, -90); 

ClosePoly(); 
setpolytemp((*pentagram)-> polySize); 


The original of the polygon is not 


changed when it is scaled and 
displayed. Instead a copy is used. 
Since the program has no idea how 
big а space to reserve for the copy, 
setpolytemp() adjusts the size 
reserved for the global handle 
polytemp. 

NO ERROR CHECKING IS DONE ON THE 
MEMORY OPERATIONS. 


setpolytenp(size) 


short size; 


if Cpolytemp equals 0) 


polytemp = (PolyHendle)NewHandle(size); 
else if (size > GetHandleSizeCpolytemp)) 


SetHandleSizeCpolytemp, size); 


makeregion() 


© The Essential MacTutor, Vol. 3 


Point Sp, ep; 
Rect г 


sp.h 
Sp.v 
ep.h 
ep.v = 68; 

theregion = NewRgn(); 
OpenRgn(); 
SetRect(&r, 0,0, 10,60); 
FrameRect(&r); 
SetRect(&r,40,0,50,60); 
FrameRect(&r); 
SetRect(&r, 10,25, 40,35); 
FremeRect(&r); 
CloseRgnCtheregion); 
tempregion = NewRgn(); 


ини 
ә 
cq 
~ 


) 


# include "abc.h" 
"include — "Quickdraw.h" 
include | "windowMgr.h" 


short currentcursor; 
CursorAdjustCw) 
WindowRecord хм; 
Point pt; 
CursHandle curs; 
GetMouseC&pt ); 
LocalToGlobalC&pt); 


if CCPtInRgn(pt, w-> contRgn)) 
and Ccurrentcursor 
notequal 2)) 


curs = (Cursor **)GetCursor 
Ccurrentcursor ); 
SetCursor(*curs); 


else 
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нчы 
) 
сайышы 
return(currentcursor ); 
CursorToUse(c) 
short e 
currentcursor = c; 
/* abc.h 
x 
* Local definitions to 
x 
x/ 
“define True 1 
define False 0 
def ine Nil 0 
define and 5 
"def ine or | 
"def inenot 


'"idef ine equals 


| 
| 
#def ine notequal ! 


/* unsigned char, longs, shorts 
* (unsigned longs may not be 
* available with all compilers 


*/ 
#def ine uchar unsigned cher 
def ineushort unsigned short 
8S def ine ulong unsigned long 


/* General purpose routines */ 


extern cher *CtoPstr(); 
extern cher *PtoCstr(); 
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Resource Roundup 
Sleuthing the New System File 


This month, I' m going to talk about the new traps available in 
System 4.1 under the Macintosh Plus — and, to a lesser extent, 
the 512, SE and Macintosh II. (When I sat down to write this 
article, I wanted to call it "Trapping System Compatibility", or 
"Seeking the Compatibility Trap," but finally decide to give up 
on the puns.) 

This all started when I was working on my book, Program- 
ming with Macintosh Programmer's Workshop (due to be pub- 
lished by Bantam this month.) I wanted to include an up-to-date 
list of traps; in particular, I wanted to pull together all the traps 
and indicate exactly when it was safe to use them. (If you have 
the book already, I' m referring to Appendix E.) 

Atthe timeI was writing the appendix, all Ihad wasthe APDA 
draft for Inside Macintosh, Volume V, which described new 
features developed for the Macintosh II. After the draft was 
published, many of the features described for Mac II were 
retrofitted for the Plus. For the Macintosh SE, some of the new 
stuff made it before the SE ROM was frozen (several months 
before the II), while other stuff also had to be retrofitted. 

I have a fastidious pre-occupation for detail, and sometimes 
I get carried away. In this case, what started out as a simple 
exercise ended up being a rather elaborate endeavor. I probably 
spent 10-15 working days over three months trying to get the 
exact answer to exactly which trap is available when. I ended up 
testing five different System files on the Mac 512, Mac Plus, 
Prodigy 4, Macintosh SE and Macintosh II. I didn't test all 
possible combinations, but all the valid ones for the Mac Plus, SE 
and II, and all but one (System 3.3, very similar to System 4.0) 
for the Macintosh 512. 

My work was assisted by the generous help of Silicon Beach 
Software, who supplied an SE and a prototype Mac II. Neil 
Rhodes also lent his production Mac II, while my former em- 
ployer coughed up the prehistoric 512. I've ignored the Macin- 
tosh XL, aka Lisa 2, since most developers traded theirs in when 
the opportunity presented itself and it never sold that well, 
anyway. 

Educated Guessing 


First let me note (standard disclaimer follows) that I am not 
privy to any confidential Apple information regarding the ROM 
or trap patches. If I were, I probably couldn't share my thoughts 
on the subject. 

However, I like to consider myself clever and resourceful, 
and I felt that a studied application of documented techniques 
would produce valuable results. Those of you who are regular 
readers of MacTutor will recognize this as "sleuthing." 

In this case, I know the availability of each by trap word 
($A000-AFFF) with certainty, both the traps that have names, 
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and those that do not. However, some of the OS traps share the 
same trap number and use high-order bits to distinguish between 
the traps, but my analysis of the trap dispatch table can't distin- 
guish this. Also, for the dispatched traps, I can't tell which new 
traps are added that share the same dispatch word. 

There are also some problems with occasional ROM traps 
looking like RAM traps, since some other interloper (like a 
development system or application) may have patched a per- 
fectly good ROM trap. From a compatibility standpoint, it's not 
as important to know which ROM-based traps are patched, so 
although there might be a glitch or two here, it's not worth losing 
sleep over. 

After pouring over all the information and asking a few 
sources for help, I know the trap names with a strong degree of 
certainty. I've left off a few traps for which I have discerned 
names because Apple has not told anyone (including me) how to 
call them, nor guaranteed that they will work in the future. There 
are quite a few traps that are defined but not named at all (at least, 
outside Apple), but presumably those are called from within the 
ROM only and subject to change at any time. 

Finally, when we get down to why a particular trap was added 
or modified, all сап do is make an educated guess. ButsinceI've 
spent so much time studying trap compatibility, I thought people 
might be interested in the results of my education. 


The Format of a Trap 


А trap is an unimplemented Motorola 68000 instruction that 
generates a standard 68000 exception vector interrupt, which is 
used by the Macintosh to transfer control to the appropriate code. 

The 68000 uses instructions that are a multiple of 16 bits, with 
many instructions contained in a single 16-bit word. In the case 
of Macintosh traps, the instructions are 16-bit words (trap words) 
in which the first hex digit is А, so these are sometimes referred 
to as "A-line" traps. All 4096 A-line traps are considered illegal 
instructions. 

(I heard a story that Motorola wanted to use A-line traps 
someday for a future processor, but with Apple machines now 
holding the majority of the chips out there, that possibility is 
gone. However, Motorola has reserved the 4096 F-line traps for 
coprocessor calls, such as for the MC68881 and MC68851 of the 
Macintosh II.) 

When it sees an illegal instruction in the range $A000 to 
$AFFF, the MC68000 (or MC68020) transfers control to the 
exception handling routine pointed to by location $028. For a 
Macintosh, this transfers control to the trap dispatcher. 

As shown by Figure 1, the range of possible traps is split into 
two groups, with $A000 to $A7FF allocated to OS traps, and 
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Figure 1: Format of trap word 
Toolbox traps sasoo - sarrr 


15 14 13 12 11 10 9 


Ж 


OS traps ѕлооо - sa7FF 


Memory Manager 


15 14 13 12 


trap number (0-255) 


trap returns value in A0 


,CLEAR clear block with zeroes 


, SYS 


File Manager, Device Manager 


15 14 13 12 #11 #10 9 8 


[ла 


,ASYNC execute asynchronously 


Other OS traps 


trap number (0-255) 


t trap returns value in А0 


$A800 to $AFFF for Toolbox traps. The lowest bits of the trap 
word are the trap number. 

All traps from $A000-$A7FF are OS traps that accept any 
parameters in low-numbered registers, such as AO and DO, 
returning any results similarly in registers. 

Most of the traps from $A800 on are Toolbox traps, which 
have parameters passed on the stack along the lines of the 
standard Lisa (now MPW) Pascal calling sequence. There are 
also a number of stack-based traps for OS managers above 
$A800, and a handful of register-based OS traps as well, but for 
our purposes, these are numbered and treated as Toolbox traps. 

The basic OS traps are numbered $A000 to $AOFF, with the 


© The Essential MacTutor, Vol. 3 


trap number (0-1023) 


,АОТОРОР RTS upon trap completion 


trap number (0-255) 


File: HFS call 
Device: bypass I/O queue 


upper 3 bits are used for other indicator 
flags. The figure summarizes what these 
flags are used for, and their hex mask 
equivalents are: 

$100 trap returns a value in AO 

$200 HFS traps 

$400 asynchronous I/O call; or 

allocate in system heap 

The $200 and $400 bits are also used 
by some other traps, including . GetTra- 
pAddress. 

There can be two (usually related) OS 
traps with the same OS trap number, dif- 
fering only in their indicator bits. For 
example, _PostEvent is $А02Е and 
_PPostEvent is $A12F. More signifi- 
cantly, _Open is $A000, while its HFS 
counterpart is _HOpen at $A200, and 
their are many similar HFS pairs. 


Trap Tables 


use system heap 


The trap dispatcher transfers control 
to the correct routine using a trap table, 
which contains the address (possibly 
encoded) of the corresponding routine. 
The trap table is always in RAM, because 
it is possible for a program to modify the 
entry for any trap, as we’ll see. 

The trap table on the original Macin- 
tosh was compressed, with only 16 bits 
for the trap address. Using the 68000 
restriction that instructions begin on even 
addresses, this allowed 64K of ROM 
addressability, plus patches in the first 
64K of low memory, presumably in the 
System Heap. 

The Macintosh 512, of course, is just 
a Macintosh (128) with more RAM; same 
connectors, maybe (as noted in earlier 
MacTutor articles) a better power supply 
— but the same ROM, traps and trap 
table. I'll talk about the 512 from now on, 
since presumably everyone has at least 512K. 

The 64K ROM also cheated by overlapping the OS and 
Toolbox trap tables into a single table. As shown in Table 1, this 
limits a Mac 512 to 512 of both kinds of traps. More significantly, 
certain trap words are not available on the Macintosh 512 — 
since that spot in the trap table is taken for the opposite (Toolbox 
or OS) purpose. 

Generally, the first 80 slots (A000 to AO4F) in the 64K ROM 
are allocated to OS traps, and the last 432 slots (A850 to A9FF) 
are allocated for the Toolbox. But a few stragglers from the OS 
take slots allowed for the Toolbox, although the ROM doesn't 
seem to care which type of trap is in the slot . 


The Plus and SE split the two trap tables. A 
full 256 OS traps are defined, and 512 Toolbox 
traps — $A800 to $A9FF — are allowed for the 
Plus and SE. When you get to the Macintosh II, 
the maximum 1024 Toolbox traps are provided, 
with the extended traps — $AA00 to $АВЕЕ — 

used for Color QuickDraw. 


ROM sizet 


Inherent Limits Total 
Some people have told me that they have a 
certain machine and wish they could have a 
certain new capability, typically offered with the 
next machine up. 
For example, many folks want Color Quick- 


Draw on their SE or Plus. While I can't say it 
won't happen, it would require some changes to the trap dis- 


patcher, because the necessary traps are not possible using the 
built-in SE or Plus trap tables. (There's also the question of how 
to get the code itself, but if there are BIOS clones in the IBM 
world, certainly the Mac world will inspire color clone conver- 
sions of the SE if there's enough demand.) 

More significantly, many people will find that there are 
certain things they cannot do and never will do with their old- 
ROM machine. The gap between the 64K ROM and the rest of 
the world is now huge and largely unbridgable; if you're not 
aware of the differences, then read on. 

First, bridging this gap would require throwing out the trap 
dispatch mechanism on the 512 to allow for more traps, with 
separate OS & Toolbox traps. However, 512K is at the low end 
nowadays for dynamic memory in the Macintosh world, and 
that's the largest configuration Apple ever offered in the 64K 
ROM world. Apple could have gone to a lot of trouble to try to 
improve marginally adequate machines (or third-party upgraded 
machines), but they didn't, per- 
haps wisely so. The clincher is 
that these old-ROM machines 
now form 20% (my estimate) of 
the installed base, and that num- 


ber is getting smaller every day. Date 


Jan 84 
May 84 
Apr 85 
Jan 86 
Jun 86 

12 Jan 87 
15 Jan 87 
14 Apr 87 


The Good Ol’ Days 


Once upon a time, things were 
much simpler. There were only 
traps and glue. There was one list 
of available traps. Occasionally, 
the glue got more elaborate in a 
new release of Lisa Pascal, but 
this was strictly a compile-time 
decision. When your program 
ran, you knew it would face only 
one set of traps. 

Along came the 128K ROM 
of the Macintosh Plus, and the 
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Possible OS Traps 
Possible Toolbox 


System Finder 
1.0 


Table 1: Trap table size 


512 


Plus SE 
128K 256K 


256 256 
512 512 
768 768 


t The ROM on the original Macintosh is the same as the 512, and the 
Macintosh 512K enhanced ROM is the same as the Macintosh Plus. 
The ROMS on the SE and II, while the same size, are very different. 
Wherever you see Plus, this includes the 512Ke as well. 


Table 2: RAM-based HFS 


Pascal name 


PBHOpen 
PBHGetVInfo 
PBHCreate 
PBHDelete 
PBHOpenRF 
PBHRename 
PBHGetFInfo 
PBHSetFInfo 
PBAllocContig 
HGetVol 
HSetVol 
PBHSetFLock 
PBHRstFLock 


Table 3: System and Finder versions 


Macintosh 


Macintosh 512 


Macintosh Plus 


Macintosh SE 
Macintosh II 


+ Resource fork labels this “Finder 2.2" 
Bold indicates preferred versions to use at this time. 


Shipped with 


Trap name 


_HOpen 
HGetVInfo 

. HCreate 

. HDelete 
_HOpenRF 
_HRename 

. HGetFileInfo 
_HSetFileInfo 
_AllocContig 
_HGetVol 
_HSetVol 
_HSetFLock 
_HRstFLock 
_HFSDispatch 


Editor’s Comments 
Original Mac OS 

minor bug fixes 

First “new Finder” release 
notorious buggy quick fix 
Most stable, long-lived 
Apple Share quick fix 

Beta for pending Mac II 

So called “Universal System” 
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world was never the same again. The 128K ROM had a whole 
list of new traps not available on the 64K ROM. All of a sudden, 
the Macintosh software architecture was nota fixed target, but an 
evolving one. 

(Its smaller sibling, the Mac 512K enhanced, has the exact 
same ROM as the Plus, with less memory and different peripheral 
interfaces, but these differences are uninteresting for our pur- 
poses and the 512Ke will be treated as a Plus for the remainder 
of this article.) 

To make matters worse, a certain subset of the 128K ROM 
traps — those involving the File Manager — were also available 
on 64K ROM machines using trap patches. All you have to do 
is place the file “Нага Disk 20" on your boot disk and you're all 
set, with full access to the Hierarchical File System of the 128K 
ROM. 

The traps patched by “Hard Disk 20” to 64K ROM machines 
are shown in Table 2. A total of 13 traps are analogous to existing 
traps, most of which add an “Н” to their corresponding 64K trap, 
such as НОреп vs. _Open. 

As their Pascal names suggests, the higher-level PBH rou- 
tines are HFS-oriented ParamBlockRec calls. In addition, the 
_HFSDispatch trap provides 11 separate routines, not shown. 

However, even with this range of options, things were easy by 
comparison to today. At least there were only three configura- 
tions: 

* Mac 512 (or a 128 for masochists) 

“ Mac 512 + HFS (using Hard Disk 20) 

e Mac Plus (including Mac 512Ke) 

Come 1987, with new machines and System files, the con- 
figuration possibilities became much, much more complex, as 
we'll see in a minute. 


Dispatched Traps 


In some cases, several routines share the same trap word. A 
trap selector is a value that distinguishes between calls to the 
different routines; a trap word that requires a selector is called a 
dispatched trap. 

In the original ROM, the only dispatched traps were the 
packages, which were disk-based resources of type ‘PACK’, 
loaded into RAM (like any other resource) in an as-needed basis. 
Six of the eight possible packages were defined, and their 


dedicated traps were: 
_Pack2 Disk Initialization 
_Pack3 Standard File 
_Pack4 SANE floating-point 
 Packb SANE trancendentals 
_Pack6 International Utilities 
.Pack7  Binary/Decimal Conversion 


The Hierarchical File System added  HFSDispatch as a non- 
package dispatched trap. System 3.0 added a new package 
( PackO) for the List Manager, while the 128K ROM included 
_SCSIDispatch. 

Now there are six more. TextEdit, Script Manager, Shutdown 
Manager and Printing Manager have four, available on all 
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systems. Specific to the Mac II is the Slot Manager, while Color 
Picker Package is primarily designed for the Mac II, but available 
on any 128K ROM machine. For five of the managers listed (all 
but TextEdit), the dispatched trap is used to support all routines 
of the manager. 

Most of the dispatched traps take stack-based parameters, and 
these use a selector on the stack. Packages use 32-bit selectors, 
while others may use either 16- or 32-bit selectors. 

The two register-based dispatched traps, _HFSDispatch and 
_SlotManager, use a 16-bit selector in register DO, and usually a 
parameter record pointer in AO. 


System Versions 


The Macintosh system software has changed tremendously 
since 1984. Table 3 gives a chronology of the System and Finder 
versions publicly released as of this writing. I’ve omitted beta 
versions and others that Apple never encouraged people to use, 
such as System 3.1 or 3.11. I couldn’t find the 1.0 disk that came 
with my original Macintosh in February 1984, but since no one 
should be using that version today, I figured it wasn’t important 
enough to go digging through storage to find its exact date. 

Until System 4.1, the System and Finder had textual version 
dates in the resource fork, in the ‘STR ‘ and ‘FNDR’ resources, 
respectively. These generally coincide with the modification 
date for the file, but where there was a conflict, I took the 
modification date (which seemed to correspond to a release date). 
Why the new System and Finder don't have dates is beyond me, 
but I hope they put them back in. Without them, it is hard to write 
utilities that indicate which version each system is running; an 
important consideration for network management. 

One interesting curiosity is the similarity of System 3.3 and 
System 4.0. They are only three days apart and share the same 
finder, and, as noted later, are very similar in the traps they 
implement. System 4.0 was obviously designed for the Macin- 
tosh SE. 

I'msure most of you have seen Apple's smiley-face compati- 
bility table for System/Finder versions and different Macintosh 
models, either in the developer mailing or in the APDA newslet- 
ter. But for further reference later on, the recommendations are 
summarized in Table 4. 


RAM patches 


Trap patches have always been with us. But somewhere 
around System 3.0 (Finder 5.1) Apple developed a formal 
scheme for implementing trap patches using *PTCH' resources 
in the System file. Since this is Resource Roundup, no column 
would be complete without at least a prefunctonary discussion of 
an interesting resource. 

One or more “РТСН” resources are loaded at startup time. 
They contain routines that will be available to all applications 
until the machine is powered off, and these routines are loaded 
into the system heap. The address of the patch replaces the ROM 
address that was previously stored in the trap dispatch table. 
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Table 4: Recommended System and Finder versions 


Machine Recommended Alternatives Editor's Comments 


Macintosh System 2.0 upgrade to 512Ke Obsolete 
Macintosh 512 System 3.2 System 3.3 Obsolete 
Macintosh 512K enhanced System 32 System 3.3, 4.0, 4.1 Minimum supported system 


‘Official’ New Product Line 


Macintosh Plus System 4.1 System 3.2,3.3, 4.0 Base line for Mac technology 
Macintosh SE System 4.1 System 4.0 Mainstay of the Mac line 
Macintosh II System 4.1 none Leading edge Mac 


Notes: 


1. AppleShare requires System 3.3 or later 

2. MacTutor strongly recommends upgrading all Macs 
to 128K ROMS, as in 512Ke to protect investment value. 

3. Apple claims 512Ke Mac will continue to be supported but 
the writing on the wall would suggest otherwise for the long term, 
due to the system heap requirements and large applications coming 
to market. An upgrade path exists for 512K to Mac Plus. 


Patches were originally intended to fix bugs in 
the ROM. Not suprisingly, no piece of software is 
done until after it’s tested, and some complex 
software only gets properly tested by end-users. 
It’s an unfortunate reality of this business that the 
most embarassing crashes only show up after 
you've shipped out 100,000 disks. 

Since the original system software releases, 
however, trap patches have taken on new impor- 
tance. They now have three uses: 

• Fix a bug; 

• Extend existing capabilities; or 

ғ Add a new trap 

Between System 2.0 and 3.2, no new traps are 
defined by RAM patches. However, after that, the 
number of traps increases significantly, particu- 
larly for the Macintosh Plus. Table 5 summarizes 
the number of documented traps for each machine 
for System 3.2 and System 4.1. System 3.2 is not 
recommended for the SE, so I listed the minimum 
configuraton of 4.0. Some people used beta re- 
leases of 4.1 on the II, but again it's not kosher, so 
the Mac II list starts with 4.1. 


Table 5: Trap counts by System version 


System 3.2t System 4.1 Maximum 

Macintosh 512 

OS traps 81 81 

Toolbox traps 411 415 

Total 492 496 
Macintosh Plus 

OS traps 100 102 

Toolbox traps 468 483 

Total 568 585 
Macintosh SET 

OS traps 110 111 

Toolbox traps 478 483 

Total 588 594 
Macintosh II 

OS traps N/A 

Toolbox traps N/A 591 

Total 


t System 4.0 for Macintosh SE 


If you have your own count of traps, it might be slightly | standpoint. It has the same Toolbox calls available, and in the 
different. There are some gray areas when it comes to defining | OS, is missing only the ADB-related stuff and a couple of slot- 


exactly what is a “documented” trap. 


System 4.1 


oriented calls. 

Table 6 summarizes the programming-level features of Sys- 
tem 4.1, primarily in the area of new and enhanced traps. The list 
is short for the 512; the other machines share most of the same 


Looking at the trap count, it's pretty obvious that System 4.1 | functionality. 
makes a Macintosh Plus almost identical to an SE from a software For those traps not provided in ROM, there are corresponding 
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"PTCH' resources in System 4.1, as shown in Table 7. Resource 
#0 is used for all systems; if the other numbers seem strange, 
they're nothing more than the concatenation of the two bytes of 
machine and ROM version returned by the _Environs trap. 
Notice how huge the trap patches are for the Mac Plus — this 
must be one important reason why System 4.1 provides a resiz- 
able system heap. 

Traps can also be patched by any other code loaded at system 
startup time, notably ‘INIT’ resources. In case you missed the 
Scoop, startup looks for files of type ‘INIT’ or ‘RDEV’ in the 
system ("blessed") folder and then runs any ‘INIT’ resources 
found there. 

Incidentally, if you're having trouble fitting System 4.1 onto 
a floppy-based boot disk, you can strip out the unused *PTCH' 
resources. If you don't have a Macintosh II, you can also delete 
all the ‘snd ’,’snth’, and ‘cicn’ resources; this saves nearly 40K 
for a Macintosh Plus. However, you should edit the ‘STR ° #0 
(version) resource and the Get Info box to indicate your hack, and 
DO NOT DISTRIBUTE THIS VERSION TO SOMEONE 
ELSE. If the modification is performed only by people smart 
enough to know how to do it, it’s much less likely to cause naive 
users to come to grief. 


New Traps 


With System 4.1, a few new traps are available on all 
machines, including the 512. 

Two,in fact, came in with earlier System versions 3.3 and 4.0, 
both released in January. Other than adding the Shutdown 
Manager, in fact, System 4.0 is almost identical to 3.3. Both 
contain the trap-based Printing Manager. 

Owners of the Macintosh 512 can also take advantage of the 
Script Manager under System 4.1, via a dispatched trap. The 
_KeyTrans trap provides a new scheme for keycode translation, 
unlike the original (low-memory global) approach described in 
an earlier column (“Ве A Keyboard Sleuth", August 1986.) 

The other new traps are provided to Macintosh Plus (and SE) 
owners tokeep up with their II-owning brethren. The use of these 
traps is described in the Macintosh II documentation, such as 
Inside Macintosh Volume V. 

The Toolbox functionality of Plus and SE is essentially the 
same as the II, except for color. The OS is different, reflecting 
three hardware-dependent differences of the Macintosh II: 

• 32-bit memory addressing 

е  NuBus slots 

e Sound Manager 

The new traps available in System 4.1 are listed in Table 8, 
along with where the trap can be found — since several made it 
into ROM on the SE and Mac II. A few traps were already defined 
in the SE's ROM, but were patched in System 4.1 to get it right. 


Enhanced Capabilities 


А number of traps are not new, but are previously ROM- 
based traps redefined by RAM patches in System 4.1. Those 
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Table 6: Features of System 4.1 


for all systems 
е Enhanced Printing Manager (System 3.3) 
е Shutdown Manager (System 4.0) 
е Script Manager 
* New keyboard translation (also in 256K ROM) 


for Macintosh Plus, SE, II 
е SysEnvirons 
e Popup menus 


for Macintosh Plus, SE (also in II ROM) 
* Menu bar definition procedures 
* Hierarchical Menus 
* Interpreting color pictures 


for Macintosh Plus (in both 256K ROMs) 
е TextEdit with styles 
* New keyboard translation (also for Mac 512) 


for Macintosh II only 
* Palette Manager 


Table 7: Trap patch resources in System 4.1 


Resource Size (bytes) 
“РТСҤ' 0 540 

*PTCH' 105 5,696 

26,884 
12,004 
12,958 


Used by 
All systems 


'"PTCH' 117 
“РТСН” 376 
"PTCH' 630 


redefined for the Mac 512 are shown in Table 9, while Table 10 
lists those for the three other machines. I don't have any way of 
knowing which patches have changed from the previously RAM- 
based traps, so these lists exclude traps that were RAM-based 
previously. 

Some of these patches are to fix bugs, but System 4.1 also 
contains enhanced capabilities for two important managers. 

Most noticeably, the new TextEdit supports what we've all 
been asking for — mixed fonts and styles in an editing record 
managed by TextEdit. Three new traps — _TEGetOffset, 
_TEStyleNew and the dispatched _TEDispatch are provided, 
while the existing TextEdit traps have been modified to use the 
new style data structure. As Table 10 shows, this is provided in 
ROM by the Macintosh SE and II, but in RAM by the Macintosh 
Plus. 

Andif you haven't heard by now, the Mac II (and System 4.1) 
provides hierarchical menus. Selecting an item from a normal 
menu causes another menu to pop up. The revised Menu 
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Manager also includes the PopUpMenuSe- 
lect trap and a menu bar definition procedure 
(type ‘mbdf’) to complement the menu defini- 


Table 8: New traps in System 4.1 


tion procedure (MDEF"). Name Trap Plus 
As an aside, new File Manager traps for 

external and shared file systems have been _StripAddress new 
provided since the original HFS release. These _SysEnvirons new 
traps are allocated as new selectors off of _InitProcMenu new 
_HFSDispatch. At least some are installed for . PopUpMenuSelect new 
those having the AppleShare client driver (an _RGetResource new 
‘RDEV’ file) in their blessed folder; the SE _SetFractEnable new 
that I tested with, for example, was using _TEGetOffset new 
AppleShare at the time. _TEDispatch new 
_TEStyleNew new 
Other Changes - GetitemCmd new 


. SetitemCmd 
. Shutdownt 
 ScriptUtil 
_Printingt 
_KeyTrans 


new 
new 
new 
new 
new 


There are a number of bug fix changes in 
System 4.1, including many I don’t know 
about. However, there are a few that either 
Apple has talked about or that I can guess to 
explain the remaining traps on Table 10. There 
are also changes that correspond more to a 
change in specification than a bug correction. 

The draft IM Volume V included notes 
about how many of the fixed-point arithmetic 
traps had problems that are now fixed. To 
summarize,  FixRound had trouble with nega- 
tive numbers, FracDiv and _FixDiv had 
problems with large quotients, and _Frac- 
ToFix and _FixToLong acted up when round- 
ing up to the next number. It's nice to know that Apple's 
programmers are human, just like the rest of us. For the 
Macintosh II,  ClosePort was patched to be able to close a 
CGrafPort (color drawing port). Earlier in the Color QuickDraw 
specification, there was a separate trap to close these ports, but 
they were later combined into one and . CloseCPort went away. 

Also, many of the Mac II traps didn't make it into the ROM- 
burning party, and had to be added to ‘PTCH’ #376. This 
includes the entire Palette Manager, not shown. 

There are many other changes I have no explanation for. Such 
changes include all of the unnamed OS traps in the range $AOBF 
to $AOFF, of which many are patched by System 4.1. I'm sure 
the folks at Apple know what these are — and probably Duane 
Maxwell at Levco, since the Levco ROM supplied with the 
Prodigy 4 patches some of these traps, according to my sleuthing. 


ROM 


f. Printing is System 3.3 or later; Shutdown is System 4.0 or later 


Legend for Tables 8-10: 
Notation was in 
new (none) 
patched ROM RAM 
unpatched RAM ROM 
ram RAM RAM 


now in 
RAM 


Table 9: Traps changed from 
System 3.2 to System 4.1 
(Macintosh 512 only) 


Word 
A031 
A930 
A9CC 


Name 

. GetOSEvent 
. InitMenus 
_TEInit 


Change 
patched 
patched 
patched 


routine SysEnvirons is now the official way to check for compati- 
bility testing The details of calling it are well-described in 
Macintosh Technical Note #129, so I won't reiterate them here. 
If you don't have the tech note in front of you, the information 
returned by SysEnvirons is summarized in Table 11. 

The rules on how SysEnvirons works and when it is available 
are interesting, and certainly relevant for a discussion of trap 
patches, so let me touch on a few points. 

Beginning with System 4.1, there's a  SysEnvirons trap 


SysEnvirons 


As you may have gathered by now, System 4.1 and the 128K 


(or later) ROM offer a lot of attractive capabilities for the 
Macintosh developer. But with all the possible configurations, 
how do you tell what is available when your program is running? 

I suspect Apple's Tech Support department anticipated a 
flurry of questions on this subject, because they proposed and 
developed a new routine just to provide such information. The 


118 


provided as a RAM patch for the Macintosh Plus, SE and II. It 
is not available on the Macintosh 512, nor is it in ROM for any 
machine yet released. Apple provides a standard "glue" routine 
for calling the trap, which will be part of MPW 2.0 and presuma- 
bly other development systems. 

The glue can be used on any machine, whether it includes the 
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Table 10: Traps changed from System 3.2 to System 4.1 
(Macintosh Plus, SE, II) 


. Read 


_FreeMem 
_SetHandleSize 


_HLock 


_HUnlock 
_GetOSEvent 
_CompactMem 
_RelString 
_RmvTime 
_PrimeTime 
_HFSDispatch 
_StackSpace 
_HGetState 
_TESelView 
_TEPinScroll 
_TEAutoView 
_InsMenultem 
_SetFScaleDisable 
_FontMetrics 
_MeasureText 
_Fix2Long 
_Frac2Fix 
_FracDiv 


_FixDiv 
_FixMul 


_FixRatio 
_FixRound 
_GetClip 
_DrawText 
_TextFace 
. FillRect 
_PtInRect 


_FillRgn 


_stdGetPic 
_DrawPicture 
_InitFonts 
_RealFont 
_SetFontLock 
_InitWindows 
_ValidRect 
_FindWindow 
_InitMenus 
_NewMenu 
_DisposMenu 
_AppendMenu 
_ClearMenuBar 
_InsertMenu 
_DeleteMenu 


Word 


Plus 


patched 
ROM 


unpatched 
unpatched 


ROM 
patched 
patched 


unpatched 


patched 
patched 
ram 
ROM 
ram 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
ROM 


unpatched 


patched 


unpatched 


ROM 

ROM 

ROM 

ROM 

ROM 

patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
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SE 


patched 


unpatched 


patched 


unpatched 


patched 
patched 
patched 
patched 
ROM 

ROM 

patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 


ROM 
ROM 
ROM 
ROM 
patched 
patched 
patched 
ROM 
ROM 


Remarks 


Also Mac 512 


Patched/ Sys 4.0 


color PICT 
color PICT 


Also Mac 512 

Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 


_SysEnvirons trap or not. Figure 2 
shows a flow chart for how the glue 
works. 

Note that the glue is more than 
just stuffing a few registers for the 
_SysEnvirons trap. Fora64K ROM 
machine, _SysEnvirons uses the 
same trap number as  StdLine, so 
it'S not practical to include a trap 
patch for it. Instead, the glue fills in 
as many values as possible fora 64K 
ROM machine, as it also does for 
the Plus (and SE) when used on a 
System version before 4.1. 

Some of this information was 
already available in low memory 
globals. Apple has recently been 
making nasty noises about notusing 
low-memory globals in the future, 
so you should use SysEnvirons 
wherever possible. Since the main 
problem with low-memory globals 
is saving their context in a multi- 
application environment (Switcher 
and its sucessors) most of the 
compatibility globals should be the 
last ones to go. After all, they don't 
changes values dynamically. 

However, as Apple discovered 
on the Apple II, programs reading 
reserved memory locations (rather 
than using ROM calls) create per- 
manent compatibility headaches, so 
if you use the ROM call, the OS can 
provide the requested information 
to you without being stuck with a 
particular memory representation 
into the 21st Century. 


Sleuth Your Own Traps 


David is never happy unless he 
getsa program with every article, so 
being a loyal columnist, I try to 
oblige him. In this case, I offer a 
way to do your own trap sleuthing. 

Anyone who can say . GetTra- 
pAddress can detect which traps are 
defined or patched. Detecting 
patches is the easiest, since the list 
of the trap patches is public record. 
To quote from Inside Macintosh, 
Volume II, page 383: 

“You can tell whether a routine 
is patched by comparing its address 
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_DrawMenuBar 
_HiliteMenu 

. EnableItem 
_DisableItem 
_GetMenuBar 
_SetMenuBar 
_MenuSelect 
_MenuKey 
_GetItmIcon 

. SetItmIcon 

. GetItmStyle 
_SetltmStyle 
_GetItmMark 
_SetItmMark 

. CheckItem 

. Getltem 
_ЅеШшет 
_CalcMenuSize 
_GetMHandle 
_SetMFlash 

. Ploticon 
_FlashMenuBar 
_AddResMenu 
. CountMItems 
_InsertResMenu 
_DelMenultem 
_GetResource 
_LoadResource 
_TEGetText 
_TEInit 
_TEDispose 
_TextBox 
_TESetText 

. TECalText 

. TESetSelect 
 TENew 
_TEUpdate 
_TEClick 
_TECopy 
_TECut 
_TEDelete 
_TEActivate 
_TEDeactivate 
 TEIdle 
_TEPaste 
_TEScroll 
_TEInsert 
_TESetJust 
_Munger 
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patched 
ram 
ram 
ram 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
patched 
ROM 
patched 
ROM 
patched 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
ROM 
patched 


Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 
Menu Manager 


TextEdit 
Also Mac 512 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
TextEdit 
_TEKey unchanged 
TextEdit 
TextEdit 


to the global variable ROMBase; 
if the address is less than ROM- 
Base, the routine is patched.” 

You have to watch out, how- 
ever, since this technique is not 
100% accurate. RAM patches 
can come from other sources, 
such as AppleShare. Also, some 
applications patch traps. For 
example, MPW patches most of 
the File Manager traps so that it 
can provide shell I/O. 

What about traps that aren’t 
implemented at all: how do you 
find them? One way would be to 
attempt to call the trap and see if 
the Macintosh crashes, but this 
would be a slow way to check out 
a list of 700 or so possible traps, 
not to mention extremely frus- 
trating. 

There is a better way. Apple 
has indirectly documented an 
approved technique to the out- 
side world recently — such as in 
the SysEnvirons tech note and 
MacApp 1.1 source code. I’m 
told it will probably be the sub- 
ject of a future tech note. 

Trap word $A89F is Apple’s 
standard unimplemented trap. If 
you get an address from the call: 

GetTrapAddress($9F) 

that is also the address of any 
unimplemented trap; just com- 
pare the address of any trap you 
check to this value. 

The example (written in 
MPW C) shows an MPW tool to 
answer the question: does this 
trap exist? This allows you to 
inquire for one specific trap, 
which I find much more handy 
than my 160K Excel file contain- 
ing all the traps for all configura- 
tions. The example also shows 
the algorithm for your own pro- 
gram to detect an unimplemented 
trap, such as whether to use the 
new TextEdit (check for TESty- 
leNew) or the Script Manager 
(try _ScriptUtil). 

The program distinguishes 
between system heap trap 
patches (presumably from the 
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Figure 2: SysEnvirons glue 


glue determines 
machine type and fills in 
default values 


64K ROM or 
Mac XL? 


Is trap $A090 
implemented? 


yes 


load AO and DO with 
parameters 


Result is value returned 
by trap in DO 


system) and application heap patches (presumably from the 
application). Neither rule is ironclad. Since there can be more 
than one application heap zone, it assumes that anything outside 
the system heap but below the ROM is in the application heap. 
Also, many programs place their actual patch in the application 
heap, but the trap table points to a single jump in the system heap 
— So the address will fit into that first 64K of low memory on a 
Mac 512. 

There are probably a few machines that violate this simple 
heuristic. Levco's Prodigy has its own PROM that is neither 
RAM nor Apple ROM, as I suspect some of the coprocessor and 
display card companies do. If you were testing on such a 
machine, you might add tests to mark those references. 


Coming Attractions 


With my book behind me, I'm now doing some interesting 
things with Color QuickDraw. If you're at the Macworld show 
in Boston (August 11-13), stop by MacTutor booth and ask for 
me if you want to see what I'm up to, or just have some 
suggestions for future topics to be covered in Resource Roundup. 

It seems like every MacTutor reader I talk to asks me about 
my promised article on how to write your own printer driver. 
Since I wrote the last article ("Printer Sleuthing," March 1987) 
I've been too busy with my book to do anything else, but I hope 
to get it to it in the coming months. 

In the meantime, if you want to write your own printer driver, 
I would note that this has never been for the faint-hearted, and 
maybe only for the foolish. Even for an extremely skilled and 
knowledgeable Macintosh programmer, it's probably several 
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man-months to get even a hack driver 
working. I personally have not done it 
(yet), which is one reason I haven't written 
the article. 

Also, Apple has never been very forth- 


Return 
envNotPresent coming with details on this subject, and 


recent indications (see Macintosh Technical Note #122: “De- 
vice-Independent Printing") are that this will be even more true 
in the future, as they make private device-dependent fields for 
their new (and current) printers. The 2.0 version of the MPW 
interfaces also delete some previously-provided information 
about print records, including the bDevCItoh and bDevLaser 
constants indicating the printer type (does this mean a new printer 
is due soon?) 

There's some good news for application writers (the majority 
of us), however, since the new trap-based Printing Manager 
increases the amount of information provided in a device-inde- 
pendent way. More in a future column! 


Table 11: Information returned by SysEnvirons 


* Machine type (e.g., Macintosh Plus) 
* CPU type (e.g., MC68000) 
* Has floating-point co-processor 


e System version (only if 4.1 or later) 
* AppleTalk version 

е Keyboard type 

* Is Color QuickDraw available? 

* Blessed folder volume number 


” 


/* IsTrep.c: Detect trap availability 


Written by Joel West in MPW C, June 1987 


Compiled as an MPW tool Cshell command); usage: 
IsTrap A010 А260 print information 
on traps $4010 and $4060 
IsTrep A800 -A838 information on all traps 
fron $4800 to $4830 


There is one option letter (which like UNIX 
and unlike MPW, must come first): 
-p show detailed “progress” information 


Status values returned: 
0 ok 


1 syntax error 
2 trap not implemented 
а 


"include «Memory.h» /* for THz heap zone ptr */ 
“include «0SUtils.h» /* for GetTrapAddress() */ 
include <stdio.h> 


8def ine UNDEFTRAP @x9F 
"def ine GETLONGCaddr) *С Clong *) addr) 

/* greb а low-memory global value */ 
"def ine ROMBase GETLONGCOx2AEL ) 


typedef short Half; 


typedef unsigned short UHalf; 
/* traps are Axxx, normally negative numbers */ 
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typedef unsigned long Addr; 
/* for unsigned address comparisons */ 


int strspnO,strlenC); 
long MyGetTrapAddr(); 
void syntaxerr(); 


THz syshz; 
define INSYSHEAPCa) Ca > Clong) syshz && a < Clong) syshz- 
»bkLim) 


mainCarge, argv) 
int argc; 
char **argv; 
( int argno, len, status; 
Boolean range, verbose=8; 
Addr trapword, trapaddr, unimpaddr, rombegin; 
UHalf oldword=9, t; 
cher *p; 


unimpaddr = GetTrapAddressCUNDEF TRAP ); 
rombegin = ROMBase; 
syshz = SystemZone(); 


argno = 1; /* parameter number */ 


if Cargno < argc && ! strcmpCergvtergnol, *-p^9))  /* -v for 


you UNIX types */ 
(  verbose**; 
агдпо++; 


if Cergno >= argc) 
syntaxerr (argv); 


if (verbose) 

{ printfC*ROM 6 #Х\п”, rombegin); 
printfC^Systen heap from 3X to 3X\n”, syshz, 

занын 


status = 0; 
for С; argno<argc; argnot+) 
range = 9; 
p = ergv(ergno]; 
if (*p == '-7) 
( ptt; 
rengett; 


len = strlen(p); 
if Clen && Теп == strspn(p, 
*0123456789ABCDEF ^2) 
sscanf Cp, ^$1x^, &trepword); 
if Crange) 
t = oldword* 1; 
else 
t = trepword; 


122 


for С; t<=trapword; t**) 
(  trepeddr = MyGetTrapAddr(t); 
printfC*Trep 31X is *, t); 
if (verbose) 
ргіп С ІХ, *, trepaddr); 
if Ctrepeddr == unimpaddr ) 
( printfC*undef ined\n”); 
кшш = 2, /* indicate result to shel] */ 


else 

if Ctrapaddr >= rombegin) 
printf Cin КОМ\п? ); 

else if CINSYSHEAPCtrepaddr )) 
printf C*petchedin^); 

else /* in application heap? */ 
printf С“оуеггіддеп\п“ ); 


г = trapword; 


else 
syntaxerr (argv); 


exit(status); 


void syntaxerr Cargv 2 
cher **argv; 


fprintf(stderr, “* Ss - invalid syntex. An^, ergv[03); 
fprintf(stderr, 4% $s - usage: Ss [-p] trep. n^, argv (01, 
ergv[0)); 

ee 


/* 

Find the trap address for a given trap word.The 128K ROM 
provides NGetTrepAddress Са glue routine), which distinguishes 
between 05 end Toolbox traps. This eventually uses the same 
trap number es GetTrapAddress, so it seems to work fine on the 
64K ROM. 

2 

long MyGetTrepAddr(trepword) 
UHelf trepword; 

( UHalf trapnum; 

ТгарТуре typ; 

if CClong)trapword < 0x0000A800L ) 

( typ = OSTrep; 

trapnum = trepword & OxFF; 
else 

( typ = ToolTrap; 

trapnum = trepword & Ox3FF; 


return NGetTrapAddress(trapnua, typ); 
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Advanced Mac'ing 


Build a Gossip Net on Appletalk in C 


Introduction 

What? I don't understand! Where's the tea? Like Arthur 
Dent these phrases have been commonly uttered by most (if not 
all) programmers who have looked at and used the chapter on 
AppleTalk. But, hopefully with the running example program 
presented here you won't hear those famous phrases quite so 
often. 

The program entitled DON’T PANIC is a simple AppleTalk 
communications program using Apple's Pascal Interface. The 
program will allow a user to become an active node on the 
network, see who else is on, and send and receive messages over 
that network. А perfect example of a simple gossip net on 
Appletalk as MacTutor's own Shelly and Mona demonstrate in 
the figures shown on the right. 

I'm assuming that you have a working knowledge of ‘C’, if 
youdonot my code is heavily commented. You should have read 
the section “Calling The AppleTalk Manager From Pascal" in the 
chapter on AppleTalk Manager. If you have not read the section 
skim it, now, then read the rest of the article. By the way, don't 
read the whole section, just the sub-sections on AppleTalk 
Transaction Protocol(ATP) and Name Binding Protocol(NBP). 

Now that you have skimed the sections lets go over some of 
the important vocabulary you should become familiar with: 


Network- a collection of 1 or more zones. 

Zone- a collection of at least 2 nodes. 

Node- a station(device) that occupies only one 
address on the zone. 

Socket- the subaddress that does all the work. 

Requester- The node that starts a session. 

Responder- The node to which the requester sent the 


first message. 


Because of the lopsided construction of the ATP, these 
definitions can change depending on the way you set up your 
application. For example, a requester could send a message to a 
responder to instruct it to be the requester, after this message. At 
that point the definitions still hold, but the logic does not. Some 
print servers do this because more data is sent to the printer than 


from the printer to the host. 
InterNet 
Address- the zone, node and socket 


numbers that are known to the net. 


Entity- the name, type, and zone by which 
a device is known. This is the only 
way you want to access other devices. 
Tuple- the result that is formed with the 


Entity and the corresponding InterNet 
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RPPLETRLK TEST DIALOG ВЕБЕ 


DEUICE NRME: DEVICE * : |80:15960 


You bet Mona! Sorry you won't be 
there. (I'll say hi to the guys for you) 


Shelly, ere you going to Boston this 
SEND THIS MESSAGE: jyeer? 


# OF DEVICES ON NET: [3 ] 
CURRENT DEUICE SELECTED: 


CURRENT NAME: |Shelley:GORILLRe* 


RECIEUED MESSRGE: 


Mona asks Shelley about Boston on gossip net 


RPPLETRLK TEST DIALOG ШЕШЕНЕ 


DEVICE NAME: Бһейеу DEVICE #: 


Shelly, are you going to Boston this 
RECIEVED MESSAGE:  |year? 


Vou bet Mona! Sorry you won't be 
there. (I'll say hi to the guys for you] 


SEND THIS MESSRGE: 


* OF DEVICES ON NET: [5.— ] 
CURRENT DEUICE SELECTED: 
oma 


Shelley responds on gossip net 
Address. 


BDSElement- (Buffer Data Structure) is a structure 
that contains information required to access 


the data dealing with a response. 


Setup 

Lets start our discussion with the function of ATCheck(). This 
function is the first step in setting up any calls to the AppleTalk 
Managerinany language. The routine takes care of checking and 
setting the two system globals, explained below, and opening the 
correct drivers and system routines. The drivers that must be 
loaded and opened are the .MPP(#9) and .ATP(#10). On the 
128k Macintoshes the NBP routines must be loaded explicitly so 
this routine checks to make sure that it is loaded — as well. 

The two system globals that should be examined before any 
thing is done with the AppleTalk drivers are the Port Configura- 
tion byte, SPConfig, and PortBUse. SPConfig located at 0x1FB, 
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contains both the current configuration for both the modem (Port 
A) and printer (Port b) ports. Figure 1 shows the layout of these 
bytes. You will notice for AppleTalk we only need be interested 
in bit number 1 of SPConFig. If this bit is set then we may not 
open AppleTalk because a Serial Driver is currently installed in 
the port. The other global is the PortBUse byte at 0x291. This 
byte tell us the current condition of port B (printer port)on the 
Macintosh 1. Currently, we only need to look at the low nibble 
and the high bit. If the low nibble is set to 4 then the ATP driver 
has been loaded and a node number has been assigned to this 
station. If the high bit is NOT set this could mean that the port is 
currently being used by some other client (If you are this far in the 
examination of the port bits, then the client is probably an 
AppleTalk client), otherwise it could be a special driver associ- 
ated with this port. (See figure 1) 
Lookup 

Now that the drivers are loaded and running you will want to 
see who or what is currently on the net. This is done through my 
routine Lookup(). In this routine you will: get this device's node 
and zone number; open a socket to receive requests; register the 
name, type, and zone, with the respective socket, node, and zone 
number on the network; do a network zone lookup; and set up to 
receive requests from other devices. 

You will notice I stated, “а network zone lookup." This is 
because of the redefinition of the wildcard ‘*’ for the zone. Apple 
had originally wanted this to be “all zones" but changed it later 
to mean “the current zone” only. So what does that mean — you 
can’t look up anything on another zone unless you know the zone 
name or number — ahead of time. I hope this will be fixed, 
otherwise you will have to write you own lookup type function. 

The node and zone numbers were assigned when you opened 
the drivers in ATCheck(). The zone number is set to zero unless 
there is abridge on the zone and then some non-zero number may 
beassigned. The node number the Macintosh receives is aunique 
number that тау or may not be the same as the last time. It is not 
a good idea to depend upon the node number being the same even 
if you have not added other devices to the net. If the user changes 
or updates the system on his or her station the number may no 
longer be the same, but the name should be. We will talk about 
the name a little bit later. 

If youare following along in the code asIexplain the different 
routines you will notice that Inside Macintosh has the argument 
atpSocket of the ATPOpenSocket() defined as a pointer to a 
byte. In my code it is a pointer to an integer. The difference is 
that Apple's byte here is 16 bits long. Don’t ask why, just watch 
out for this inconsistency , it took me three day to find this 
oversight (thanks Steve). 

A zone lookup is done quite simply. By setting six fields in 
the .nbpProto and calling the NBPLookup() function you will 
get back all of the named entities known on the current zone. If 
you are wondering how to filter out unwanted responses you set 
the elements of the .nbpEntity structure to what you want re- 
turned. The entity is a character string representation of a name 
(object), a type and a zone. So, lets say you only wanted every 
thing from type “GORILLA”; you would just set the type to 
*GORILLA" and leave the name (object) and zone in the wild- 
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PortBUse 7 6 


Current Use 


Driver Specific 4: ATP Loaded 


UseBit O = in use currently. 


SPConfig 6—5 
Ox1FB 


Port B 
:O unconfig 
:1 AppleTalk 
:2 Serial Drv 


Port A 
Figure 1. The two globals PortBUse and SPConfig. 


card state. 

Another structure we have not seen is the retransmission 
information. This structure contains two byte quantities that 
specify the time-out, in 8 tick quantities, and the number of retries 
the system should attempt during the NBPlookup() calls. You 
want the time-out to be large because some device may be busy 
and may not be able to respond immediately If the retries is set 
to 0 the system will execute the call O times. (It should be noted 
here that most of the other calls requiring the retransmission 
information take the time-out in seconds and the retries as n + 1 
times). The buffer that holds the returned tuples is accessed by 
the pointer .nbpBufPtr. The size of the buffer should be large 
enough to handle all expected tuples: 33 bytes for the object, type, 
and zone; and a byte each for the socket and node, then an integer 
for the zone number. 


To keep the code simple you want to make this call synchro- 
nous. The number of named entities on the zone are returned in 
nbpDataField. This field is set to 0 and incremented with each 
tuple found. It does not include your name because a requester 
and responder can not be on the same node. And if you don't 
know who you are you're in sorry shape. 

Notice that the Receive() function is called a total of five 
times. This is for two reasons. One, you should be able to receive 
more than one request at a time. You may not be able to respond 
to more that one at a time, but you should be able to receive them. 
Second, when most of the asynchronous Pascal Interfaces 
routines complete they post an event in the event query that looks 
like a Request from another Macintosh and use up the queued 
ATPGetRequests(). The actual calls to NetReg() and Receive() 
are covered below. 

Net Registration 

The NetReg() routine does exactly what the name implies. It 
takes a name (or object), a type, a zone and attempts to register 
them in the socket listening table. This is done so other devices 
can do a lookup and see your device is active on the network. The 
structure myEntity contains the name of your Macintosh, this is 
retrieved from a dialog item that came originally from an owned 
system resources(- 16096). The type can be set to just about any 
thing you want, I put in “GORILLA”; and the zone field set to the 
current zone, ‘*’. The character array myEBuff is used internal 
to NBP. The .aSocket field should be filled with the socket 
number you opened to receive requests through. I did the call 
synchronously to keep track of any errors that might have 
occurred. 

Receiving Requests and Sending Responses 
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The setup to receive a request is probably the simplest of all 
the calls. Before calling the ATPGetRequest() the following 
fields must be set up. The field .atpSocket, must be set to the 
socket number returned when from ATPOpenSocket(). The 
fields .atpDataPtr andatpReqCount should be set toa buffer large 
enough to store the requests. I'm using a buffer of 256 bytes 
because you are limited to 256 bytes in a Pascal string. The call 
is done asynchronously, if you do it synchronously you will be 
hung here waiting for a request to come through. 

Once you receive a request you should respond to whatever 
action the request required. DON’T PANIC just sends a message 
saying “... I got your request everything is OK ...”. In a higher 
level application the request may have asked for data from a disk 
or the current processor status. The data that is going to be sent 
back is referenced by the Buffer Data Structure (BDS) and is 
known through the .atpRspBDSPtr. If your higher level applica- 
tion has sent out more that one request and expects back more 
than one response you will need to keep track of which responses 
correspond to the correct requests. This is done through the 
atpTransID. My program deals with only one response so, I just 
set the .atpTransID to the request ID. The .atpEOM is set to 
TRUE and the .atpNumBufs and .atpBDSSize fields are set to 
one; because DON'T PANIC sends only one BDS. The 
requester's InterNet Address is contained in the fields of .aNet, 
.aNode, and .aSocket of the request record. The socket the 
response is sent through is set in the .atpSocket field of the 
response record. I choose to send it through the socket which my 
requests are received. Depending on which way your application 
is set up you may want to do this action either asynchronously, 
or synchronously. Given a choice I always choose synchro- 
nously, because it makes the overall program structure simpler. 

A little on BDSElements. The BDS is just a structure to hold 
information about the data. It has a pointer to and the size of the 
data as well as a userbytes and buffer size. This means that the 
data itself should be in some safe area that does not move around 
when the system does a heep compact. DON'T PANIC uses a 
global character array for the data, it send the same response 
message every time. 

Extracting Target and Send Requests 

The first step in sending a request to another device is 
choosing that device. There are some restrictions in choosing 
that device in DON’T PANIC. One, the device should be in the 
lookup list; if it is not it probably is not an active device on this 
zone. Two, it must be of the type “GORILLA” to return the 
correct response. Because we did a Lookup() with no filter all 
named devices on the current zone will be listed. 

Setting up the NBPExtract() routine can be a little tricky. 
The second argument to the function is the number of tuples in the 
list. This is contained in the .nbpDataField of the abrecord passed 
to NBPLookup(). The pointer variable, thebuffer, should point 
to the same buffer used during the NBPLookup(). Also, you 
must have defined structures of the type EntityName and Ad- 
drBlock. These two structures store the name and InterNet 
Address of the selections referenced by the argument whichOne. 
WhichOne is an integer that specifies which element of the tuples 
array should be set in the AddrBlock and EntityName structures. 
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Now that we have selected our target lets set up the request. 
The request contains a Pascal string that you entered using a 
editable field in the dialog. The address of the target is contained 
in the AddrBlock which was set in the NBPExtract() call. So, 
set the .aNet, .aNode, and .aSocket in the request abrecord to the 
.aNet, .aNode, and .aSocket of the AddrBlock respectfully. Now 
set up the data part of the request using the .atpReqCount and the 
atpDataPtr. The .atpRspBDSPtr is set to the element that will be 
used when a response is received. The .atpXO is set to FALSE 
because, we do not wish to sent as an exactly once transaction 
type. If you glance down to the end of the routine there is a call 
to the routine Receive(). This is to offset the event posted 
asynchronous call to ATPSndRequest() is completed. 

Event Processing 

Now that we can send requests, receive requests, send re- 
sponses and receive responses; how do we deal with them? When 
you receive a request or send a request, an event of the type 
networkEvt is posted. So, just like any other event you process 
it in your main event loop. To cope with the event I defined a 
routine DoATNet() that has only one argument. The argument 
is the event’s message field which contains a handle to the 
abrecord associated with this event. 

In the DoATNet() routine I look at the handle to see if it 
belongs to a request I sent or a request some other device sent. If 
I sent the request two possibilities occurred. One, the routine 
completed and a response was received; in that case I process the 
response. Two, the routine completed and no response was 
received. Ican tell the difference by examining the .atpNumRsp 
of the record. If the .atpNumRsp is greater that 0 a response was 
received. 

If the event was a request that some other device sent I place 
the data pointed to by .atpDataPtr in the dialog static text field. 
Then I send a response to the requester. If you were writing a 
higher level application you would act on the request and then 
send the appropriate response. 

Closing 

When closing your AppleTalk application you should close 
all opened sockets and remove your station from the socket 
lookup table. This is done by calling ATPCloseSocket() and 
NBPRemove() respectively. 

Notes 

You may have noticed that I have not talked much about the 
dialog. This was not an oversight. I did not want to make this 
article any longer. Justa few notes though. The code presented 
in the file main.c is every thing you need to work the example. 
The code is solid so don't play with it. If you do, I don't know 
what will happen. The code is very plain, handling just what it 
has to and nothing more. The resource output, from MPW 
DeRez, is presented at the end of the article. If you don't have a 
resource complier available I have given a numbered printout of 
the screen(Figure 2). The important items have a small numbers 
next to them. If you change the items listed just change the 
#defines in the headers. You should also include the resource 
'atpl' from the ATalk/ABPackage in your application resource. 
This file contains a small bit of glue code that most Pascal 
Interfaces need. 
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You should also include the library 
AppleTalk.Lib in your project, for a full list 
just see Figure 3 . 

Notes on LS C 

[Think Technologies hasreleased Light- 
speed C 2.11, which was used to compile 
this code. However, despite Think's claim 
that 2.11 is Macintosh II compatible, this 
code does not work on a Mac II. It crashes 
with an ID 1 error when you attempt to send 
a message. It does work on a Plus with the 
new system files. Think admits that version 
2.11 does not include the latest Appletalk 
software available and suggest you contact 
the company about getting this. If you iden- 
tify why this program doesn't work on the 
Mac II as written, please write to the Editor 
care of MacTutor. -Ed] 

The All Important Users Guide 

Before double clicking on the applica- 
tion icon go to the DA "Chooser". There, 
type the name you wish to be known by on the network. Now you 
are ready to enter the world of networking — good luck and may 
the force be with you! 

After the window is put up the drivers are opened and your 
node number is assigned. By clicking the button "LOOKUP" 
your current node number and the socket number you received 
will appear in the upperright corner. After the lookup is complete 
you will see the total number of named entities plus one appear 
in the middle of the right hand side. Then by clicking the button 
*DISPLAY" you can choose a target. After you have typed a 
message in the edit field click the send button once. If you click 
it more than once you will queue up the whole new ATPSndRe- 
quest() process. Also, you could run the risk of hanging your 
Macintosh if you queue up too many requests. By the way don't 
send messages to tuples that are not of the type “GORILLA”. 
[Mona and Shelley just LOVE seeing that description on their 
screens! -Ed] 

Conclusion 

Apple has updated their Pascal Interface to AppleTalk. The 
update is available from APDA as fKMSAMU. The update fixes 
some known bugs in the Interface and removes the glue code in 
the ‘atpl’ resource. It also does much more but I'm not going to 
cover that. Even with the update the Pascal Interface is still 
buggy. Applerecommends that you do all “real” AppleTalk calls 
through PB Block type call using the Device Manager. If there 
is time I will try to write another article using the Device Manager 
call to replace all the calls presented. But until then read the three 
articles on AppleTalk in MacTutor's September and October 
1985. They were written by Bob Denny and Alan Wootton and 
are very good. 

Ty Shipman is a contract programmer and can be reached in 
San Diego, CA. 

/* 


THIS PROGRAM WILL OPEN A NODE ON THE APPLE 
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Е ны DON'T PRNIC RN RPPLETRLK RPPL. 


Figure 2. The lay out of the DON'T PANIC Dialog Box. 


TALK NETWORK. IT WILL THEN FIND ALL THE NODES OUT THERE. 
IF THE USR ENTERS A MESSAGE IN THE EDIT FIELD AND PRESSES 
“SEND” THE USR CAN ALSO OPEN A RECIEVING SOCKET FOR PACKETS 
SENT TO IT. 
FILE: 
ATSIMPLE . C 
BY: 


TY SHIPMAN 
(C) Copyright 1987 Ty Shipman for MacTutor 
All Rights Resereved by author. 
This notice must appear in all copies. Commerical use of this 
code forbidden, without prior written permission of the 
author. 


include “MacTypes.h” 
®include "DialogMgr.h^ 
include “EventMgr .h^ 
*include *ControlMgr h^ 
include “DON’T PANIC.h^ 


/* GLOBALS NEEDED TO RUN PROGRAM */ 

WindowPtr myWindow; /* dialog window struct */ 
EventRecord myEvent; /% event that just happened*/ 
Handle NodeName; /* name rsrc hndl Cchooser) */ 


ngainC) 
( 


InitGref C&thePort); 

InitFonts(); 

FlushEvents( everyEvent, 0 ); 

Ini tWindows( ); 

Ini tMenus(); 

TEInitd); 

Ini tDialogs(OL); 

InitCursor(); 

MaxApp 1Zone(); 

ГС !SetupC) ) 

while CDEventC2) ; 

ExitToShe11C); 


аз 
ifC PutUpWindow() ) /* get window */ 


return(1); 
return(9); 
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) 
fia г 
/* this routine will put up the dialog specified and init 


811 buttons to default condition. It will also check to see 
if the ports are configured for AppleTalk or not. */ 


ControlHandle — itemHand; 
int type; 
Rect Se 1Box; 


CouldDialog(DIALOG_ID); /*read into memory*/ 

myWindow = GetNewDialog(DIALOG_ID,NIL, (WindowPtr )- 1); 
NodeNeme = GetResourceC'STR ', -16096); /* Chooser unit name*/ 
LoadResource(NodeName); /* station Chooser name */ 
SetPort(myWindow);  /* hook in quickdrew */ 
GetDItemCmyWindow,DISPLAYB, &type , & i temHand, &Se1Box2; 
/* THE DISPALY BUTTON, NO ITEMS IN LIST YET */ 
HiliteControlCitemHand,255); /*part 255, dim out*/ 
GetDI temCmyW indow, SENDB, & type, &i temHand, &5е1Вох ); 

/* 1 DON’T KNOW WHOM TO SEND TO YET */ 
HiliteControlCitemHand, 255); /*part 255, dim out*/ 
WindUpdateC ); /* do all the boxing necessary */ 


ifC ATCheckC) 2 
гешгпС 1); 


/* at this time get net stuff */ 


ShowWindow(myWindow); /*a11 of a sudden up*/ 


return(C0); 

DEvent¢) 

WindowPtr whichWindow; 
int item; 
DielogPtr theDialog; 
SystemTask(); 


( (GetNextEventCeveryEvent, &myEvent)) 
"a (nyEvent . what) 


case driverEvt: 
cese networkEvt: 


DoATNet(myEvent.message); /*param block */ 
Ies 


case mouseDown: 
Switch (FindWindow( myEvent where, 
&whi С )) 


case inGoAway: 
if (TreckGoAwayC myWindow, myEvent.where) ) 


CloseATC); 
return(0); 
im. 
cese updateEvt: 


WindUpdeate(); 
break; 


default: ; 
) /* end of case myEvent.what */ 


IsDialogEventC&mgEvent); 
if C DialogSelectC&myEvent , &theDialog,&item) ) 
ifC theDialog == myWindow) 
/* some DA’s are Dialogs */ 
DoATDialogCitem); 
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) 
else 
( 
IsDialogEventC&myEvent); 
/* so the caret blinks x/ 
DialogSelectC&myEvent , &theDialog,&item); 


return(1); 


DoATDialogCiten) 


int item; /*the item just hit*/ 


( /* respond to the item hit on the dialog */ 
switchCitem) 


case LOOKB: 


LookUp(); 
break ; 


a DISPLAYB : 


Display(); 
break; 


) 
as SENDB : 


Send(); 
break; 


default: 
break; 
)/*end switch*/ 


WindUpdateC) 

( /* drew all the stuff mwhen an update occures */ 
ControlHandle itemHand; 
int type; 
Rect 5е1Вох; 


GetDItem(myWindow,RECM, &type, & i temHand, &Se 1Box); 
InsetRectC&SelBox, -1, -1); 

FrameRect (&Se1Box); уж RECIEVED MESSAGE BOX */ 
GetDI tem(myW indow, MYNODE ,&type, & i tenHand, &Se 1Box); 
SetITextCitemHand, (*NodeName)); /% name set is chooser */ 
FrameRect(&SelBox); /* WHOM AM I FIELD */ 

GetDI temCmyW indow, MYNUM , &type, & i temHand, &Se1Box); 
InsetRect(&Se1Box, -2, -2); 

FrameRect (&Se 1Box); уж WHOM AM I node number*/ 
GetDI етту indow, SENDM, & type, &i temHand, &Se1Box2; 
InsetRectC&SelBox, -2,-2); 

FrameRect(&SelBox); /* WHOM AM I FIELD */ 

GetDI temCmyW indow, NUMBER, & type, & i temHand, &Se 1Box ); 
InsetRect(&Se1Box, -2,-2); 

FrameRect(&SelBox); /* NUMBER OF NODES/SOCKETS */ 
GetDI temCmyW indow, CNODEIS, & type, & i temHand, &Se 1Box); 
InsetRect(&Se1Box, -2,-2); 

FraneRect(&Se1Box); /* CURRENT NODE NUMBER * 

GetDI temCmyW indow, CNODENUM ,&type, &itemHand, &SelBox2; 
InsetRect(&Se1Box, -2,-2); 

FrameRect(&SelBox); /* CURRENT NAME OF NUMBER */ 


/* 
File: 
“Don’t Panic” 
an AppleTalk application 


Ty Shipman, Gorilla Software Systems 


(С) Copyright 1987 Ty Shipman for MacTutor 
All Rights Resereved by author. 
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: DON'T PANIC 


Appletalk.Lib "$3 
MacTraps 


„PrLink.Lib CCCO4——— 42. 
DON'T PANIC code.c 


„DON'T PANIC maine | 814 
stdio 
strings 


Figure 3. DON'T PANIC Project. 


This notice must appear in all copies. Commerical use of this 


code forbidden, without prior written permission of the 
author. 
ay 


®include “MacTypes .h^ 
include “DialogMgr .h” 
®include “EventMgr .h^ 
®include *ControlMgr.h^ 
include “Appletalk.h” 


include “DON’T PANIC.h^ 
/* all the globals*/ 


CurEntity — NowEnt ity; /* target for request */ 

char *ErrMess; /* ptr to error message */ 
ABRecHandle atpRec; /* handle to the above */ 

Str255 atpRecBuf ; /* hold request deta in */ 

int RecSocket ; /* receive requests */ 

char LUBuffer[20900]; /% my lookup buffer */ 

int Extractwhere; /* place in extract list */ 
ABRecHandle myABRecord; /* for my mac reg on net */ 
EntityName myEntity; /* store пате, type, zone */ 

char myEBuf f С 1051; /* wasted space, max 105 */ 
ABRecHandle Responce; /* for responce stuff */ 

BDSE lement RspBDS; 

char *BDSmess = “\pI recieved your message, requester”; 
BDSPtr nyBDSPtr; /* used in the request stuff */ 
BDSElement myBDS; /* used to reference responce */ 
char nysBuffer[512]; /* store responce here */ 


ABRecHandle SendRec; 
/* end of globals */ 


extern DialogPtr 


co 


пуй indow; 


/* allocate all the records needed */ 

myABRecord = САВЌесНапо1е )NewHand1e(sizeof CABusRecord)); 
/*for my mac reg on net */ 

Responce = CABRecHand1]e)NewHandle(sizeof CABusRecord)); 

SendRec = CABRecHandle)NewHandle(sizeof CABusRecord)); 


co 


char *PortBUseP; 
char *SPConfigP; 
cher use, con; 
int error; 


/* & pointer to PortBUse Byte */ 
/* SerialPortConfig byte */ 
/* storage for pointer contence*/ 


/* check to see if the port is set up for 

AppleTalk. It will also load the ATP, NBP, and 

апу other packeges necessary for AppleTalk. 
х/ 
CouldDialogCERRDLOG ID); /*read into memory*/ 
PortBUseP = (char *)(PortBUse); /* a ptr to PortBUse Byte*/ 
SPConfigP = Ccher *)CSPConf ig); 
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/* a pointer to SerialPortConfiguration byte*/ 
use = *PortBUseP; /* get the data */ 
con = *SPConf igP; /* get the dete */ 


ifC (соп & @x@F) > useATalk ) 
( 


ErrMess = “\pSomething wrong with the 
port(config). Exit пон!” 

ErrDial(); /* put up error message in dialog */ 

return(1); 


ifC (изе & OxFF) || € Cuse&@x@F) == useATalk) ) 


/* port is currently closed, open as I like 
or it’s AppleTalk */ 
ifC !CIsMPPOpen()) 2 


" Cerror = MPPOpen()) != noErr) 


ErrMess = “\pSomething wrong with the portCMMP). 
Exit now, and restart your system! ^; 

ErrDial(); 

/* put up error message in dialog */ 

return(1); 


) 
ifC !IsATPOpen() 2 


if€ Cerror = ATPLoad(€)) != noErr) 


ErrMess = “\pSomething wrong with the portCATP). 
Exit now!^; 

ErrDial(); 

/* put up error message in dialog */ 

return(1); 


*PortBUseP |= 0x04; 
*PortBUseP &= OxTF; 


/* ATP loaded */ 
/* in use set, set-0*/ 


t Cerror = NBPLoad()) 2 /* only on 128 MAC’s*/ 


ifCerror != noErr) 


ErrMess = “\pSomething wrong with the port(NBP). 
Exit now!^; 

ErrDial(); 

/* put up error message in dialog */ 

return(1); 


) /* end test on port config and use */ 


else 
( 
ErrMess = “\pUse bits not correct’; 
ErrDial(); 
return(1); 
*SPConfigP |= 0x21; /* set for appleTalk */ 
doAlloc(); 
return; 
) 
co 
/* lookup everything on current zone. */ 
long junk long; 
Str255 string, jstr; 
char *tempstr; 
int nyNet,myNode; 
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AddrBlock ^ atpaddrs; 
/* a filter of who I receive requests through */ /* in 8 tick counts, 75 = 18 sec*/ 

EntityName searchEntity; (**myABRecord) .nbpProto.nbpRetrensmitInfo. retransCount = 2; 
/* who I should search for during lookup */ /* set up the retry stuff */ 

Handle itemHand; if C (NBPLookup(myABRecord, SYNC) != noErr) 2 

int type; ( 

Rect SelBox; ErrMess = "\pSomething wrong NBPLookupTo many node maybe?”; 

int error; ErrDial(); 


ifC atpRec == 0 ) 
( junklong = Clong?(**myABRecordD.nbpProto. nbpDataField + 1; 


/*.nbpDataField tells how may named enities were on the nett/' 
НЫ junklong > 1) 


/* only executed first time it is called */ 
atpRec = CABRecHandle)NewHandle( sizeof (ABusRecord)); 


/* record for the ReceivedRequest */ 
RecSocket = MYSOCKET; 
atpaddrs.aNet = Сіп(20; 
atpeddrs.aNode = (Byte)0; /* wild, all */ 
atpaddrs.aSocket = (Byte)0;  /* wild, all */ 

ifc е = ATPOpenSocketCatpaddrs,&RecSocket)) != noErr) 


Ge tDI temCmywW indow, DISPLAYB, &type, & i temHand, &Se1Box); 
HiliteControlCitemHand,@); /*part®, turn on*/ 
/* wild, all */ ) 
NunToStringC junklong, string); 
Ge tDI temCmyW indow, NUMBER, &type , & i temHand, &Se1Box); 
SetITextCitemHand,string); /% display how may */ 
Extractwhere = 1; /* start here on extract */ 
Кесеіуе(0); 
/* now that someone maybe оп the system set up to 
receive а request */ 
Receive( 1), 
Receive( 1); 
Receive( 1); 
Receive( 1); 
/* put in а bunch of request receives in the que */ 
return(@); /* good return */ 


) 
coe 


ErrMess = “\pSomething wrong ATPOpenSocket. ^; 
NumToStringC Clong error, string); 
Pappend(ErrMess,string); /* give error number */ 
ErrDial(); 
return(1); 
/* for some error control return 1 
else return a 0 */ 


) 

NetReg(); 

/* register name and node/socket on net */ 
if C GetNodeAddress(&myNode, &myNet) != noErr) 


/* Done only to display on the screen, not /* this routine will register name, type on net */ 


necessary normally because I have opened the receive Handle i temHand ; 
socket above I know the InterNet address. */ int type; 
ErrMess = “\pSomething wrong GetNodeAddress’ ; Rect SelBox; 
ErrDial(); char *tempstr; 
Str255 string; 
junklong = Стућоде); int error; 


NumToStringC junklong, jstr); 

/* put the node number in a char string */ 
Pstrcopy(string, jstr); 
tempstr = “\p:’; /* just a colon */ 
Pappend(str ing, tempstr ); 
junklong = RecSocket; 

/* no longer contains 8,convert to string*/ 
NumToStr ingC junklong, jstr); 
Pappend(str ing, jstr); /* add to string */ 


/* set up the name, type, and zone of this Mac */ 

GetDItem(mnyWindow,MYNODE , & type, & i temHand, &Se1Box2; 
/*my usr name, set with the chooser */ 

GetITextCitemHand, &myEntity.objStr); /* put in usr name */ 

tempstr = "ApGORILLA^; /* a Ty Shipman Type! */ 

Pstrcopy(myEnti ty. typeStr, tempstr 2; 

tempstr = *Ap*^; /* current zone */ 

Pstrcopy(myEnt i ty. zoneStr, tempstr); 

C**myABRecord) .nbpProto.nbpEntityPtr = &myEntity; 
/* set up my name */ 

(**myABRecord).nbpProto.nbpBufPtr = (Ptr )&myEBuff; 
/* used internal by NBP */ 


tempstr = “\pé’; 
Pappend(str ing, tempstr); 


junklong » myNet; 
NunToStr ingC junk long, jstr); 
Peppend(str ing, jstr); /* add net number */ 


(**myABRecord) .nbpProto.nbpBufSize = sizeof (myEBuff ); 
(**myABRecord) .nbpProto.nbpAddress.aSocket = RecSocket; 
/* can not be allocated on fly, set to opensocket */ 


GetDItemC myWindow,MYNUM, &type, &i temHand, &SelBox); 
SetIText(itemHand, string); 
/* display the InterNet Address */ 


C*¥*myABRecord) .nbpProto .nbpRetransmitIinfo.retransInterval = 7; 
/* in seconds */ 
C**myABRecord) .nbpProto .nbpRetransmitInfo.retrensCount = 1; 
/* register the name on the system */ 
/*now I have my name and node I want to know everyone else */ ГС Cerror = NBPRegister(myABRecord,SYNC) ) != noErr) 
tempstr = “\p="; /*wild card for obj and type*/ ( 
Pstrcopy(searchEntity.objStr, tempstr); 
Pstrcopy(searchEnt i ty. typeStr, tempstr); 
tempstr 2"Mp*^; /* wild сага for this zone only */ 


Pstrcopy(searchEnt ity.zoneStr, tempstr); /* this zone is */ 


ErrMess = “\pSomething wrong with NBPRegister, try a 
different name.^; 
NumToString€ Согд )еггог, string); 
Pappend(ErrMess, string); 
/* give me the error number */ 


(*¥¥*myABRecord).nbpProto.nbpEntityPtr = &searchEntity; ErrDial(); 

/* set up filter for search of net */ return(1); 
(**nyABRecord).nbpProto.nbpBufPtr = (Ptr &LUBuffer [8]; 

/* used internal by NBP */ return(0); 
(**myABRecord).nbpProto.nbpBufSize = sizeof C(LUBuf fer); 

/* where the returned names go */ ReceiveCredo) 
(*¥myABRecord).nbpProto.nbpDataField = 100; int redo; 


/* about 100 node out there??? */ 


(**myABRecord).nbpProto.nbpRetransmitInfo. retransInterval=75; /* place a GetRequest in the Que */ 
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int — error; ) 

547255  tempstr; DisplayC) 

"a redo == 0) /* display all nodes/sockets on the screen */ 
(**atpRec).atpProto.atpSocket= RecSocket; Handle i temHand; 
(*¥atpRec).atpProto.atpReqCount = 255; /* not len byte*/ int type; 

(*XatpRec).atpProto.atpDataPtr = (Ptr &katpRecBuf ; Rect SelBox; 
Str255 currstrg, string; 

) /* my sting to store message */ cher *tempstr; 

(t Сеггог = ATPGetRequestCatpRec, ASYNC)) != noErr) ifC CC#*myABRecord).nbpProto.nbpDataField) <= 8) 

return; 
ErrMess = “\pSomething wrong ATPGetRequest.^; /* just in case there is nothing in the lookup */ 
NumToStringC ClongDerror, tempstr); if € CNBPExtractCCPtr И Ви? fer , C**myABRecord). 
PeppendCErrMess, tempstr); nbpProto.nbpDateField, Extractwhere,&CNowEnt ity. 
ErrDial(); CurName ),&CNowEntity.CurAddrs)) ) != noErr) 
гешгпс 1); ( 

) ErrMess = "MpSomething wrong NBPExtract.’; 

return(C0); ErrDial(); 

SendResponceCrequest) GetDI temCmyW indow, SENDB, &type, &i tenHand, &Se1Box); 
т request; HiliteControlCitemHand,0); /*part@, turn on*/ 

/* This routine will send a response to а request from /* hes nothing to do with AppleTalk, just so I cen display 
enother device. The socket I want to send the response to is it on the screen. Uses the standard display format of name : 
contained in the request packet. */ type @ zone */ 
errant /% а temp area */ PstrcopyCcurrstrg, NowEntity.CurName.objStr ); 

947255  tempstr; tempstr = “\p:’; /* the seperator for name and type */ 

SetupRsp(&RspBDS , BDSmess , 256); Pappend(currstrg, tempstr ); 

/* copy message to BDS specified */ Pappend(currstrg, NowEnt i ty . CurName . typeStr 2; 

C**Responce).atpProto.atpSocket = RecSocket; tempstr = “\pe’; /* the seperator for name and type */ 
/* send out socket which request was sent */ Pappend(currstrg, tempstr ); 

(**Responce).atpProto.atpAddress.aNet = Pappend(currstrg, NowEntity.CurName.zoneStr ); 
(**request).atpProto.atpAddress.aNet; GetDI temCmywW indow, CNODEIS, & type, & i temHand, &Se 1Box); 

/* contains the requesting address */ /* do the name */ 

(**Responce).atpProto.atpAddress.aNode = SetITextCitemHand, currstrg); 
(*4request).atpProto.atpAddress. aNode; 

(*¥*Responce).atpProto.atpAddress.aSocket = NunToStringC Clong)NowEntity.CurAddrs.aNode, string); 
(**request). atpProto.atpAddress .aSocket ; PstrcopyCcurrstrg, string); 

(**Responce).atpProto.atpRspBDSPtr = (BDSPtr)&RspBDS; tempstr = “\po’; /* just some filler */ 

/* pointer to BDS, data should be in BDS */ Pappend(currstrg, tempstr ); 

(*#Responce).atpProto.atpTransID = NumToStringC ClongNowEntity.CurAddrs.aSocket, string); 
(**request).atpProto.atpTransID; Pappend(currstrg, string); 

(**Responce).atpProto.atpEOM = TRUE; Ge tDI temCmyW indow, CNODENUM,,&type, &itemHand, %5е1Вох); 

/* only one responce here */ SetITextCitemHand, currstrg); 

(**Responce).atpProto.atpNumBufs = 1; 

/* only one buffer envolved here */ /* all done with the screen display */ 

(**Responce).atpProto.atpBDSSize = 1; 

if€ Cerror = ATPSndRsp(Responce,SYNC)) != noErr) ifC CExtractwhere < (**myABRecord).nbpProto.nbpDataField) ) 

( Extrectwhere**; /* the next time */ 

ErrMess = *\pSomething wrong ATPSndRsp."; else 

NunToStringC ClongJerror, tempstr); Extractwhere = 1; /* reset to beginning of list */ 
Pappend(ErrMess, tempstr ); return; 

ErrDial(); ) 

return( 1); co 2 

returnC0); /* send а request that contains the editable 
) text field of the dialog */ 
SetupRspCBDS, ness, size) 

BDSElement *BDS; /* ptr to BDSElement to use */ int error; 
char *ness; /* the message I ат to copy in */ 517255 tempstr; 
int size; /* number bytes to copy into BDS */ Handle i temHand; 
{ int type; 
Rect 5е1Вох; 
BDS->buffSize = mess(0] + 1; 
/* only one packet, of max 256 bytes*/ myBDSPtr = (BDSPtr )&myBDS; 
BDS->buffPtr = mess; /* ptr to data to send */ myBDSP tr (8)->buffPtr = (Ptr &mysBuf fer [0]; 
/* buffer that will contain message */ 
/* Notes: nygBDSPtr[2]-»buffSize = 512; 

.dataSize set by reciever of this packet. i.e. the re GetDI temCmyW indow, SENDM, & type, & i temHand, &5е1Вох ); 
quester. GetITextCitemHand, (Ptr &mysBuf fer (21); 

.userBytes set by sender in ATP.*/ /* put in message */ 
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(**SendRec).atpProto.atpAddress.aNet = 
NowEnt i ty . CurAddrs .aNet; 
C**SendRec2.atpProto.atpAddress .aNode = 
NowEnt i ty . CurAddrs .аМоде; 
(**SendRec).atpProto.atpAddress.eSocket = 
NowEnt i ty . CurAddrs .eSocket ; 
/* setup the target address */ 


(**SendRec).atpProto.atpReqCount = PLength(mnysBuf fer); 
(**SendRec).atpProto.atpDataPtr = (Ptr )&mysBuf fer [0]; 

/* setup the request data */ 
(**SendRec).atpProto.atpRspBDSPtr = CBDSPtrO&myBDSPtr; 
C(**SendRec)2.etpProto.atpXO = FALSE; 

/* set to NOT exactly once */ 
(¥*SendRec).atpProto.atpTimeOut = 4; 
(**SendRec).atpProto.atpRetries = 2; 
(**SendRec).atpProto.atpNumBufs = 1; /* one BDS element */ 
(**SendRec).atpProto.atpNumRsp = Ø; /* set to no resp yet*/ 
ifc bd = ATPSndRequest(SendRec,ASYNC)) != noErr) 


ErrMess = “\pSomething wrong ATPSndRequest. ^; 
NumToString€ ClongJerror, tempstr); 
Pappend(ErrMess, tempstr ); 

ErrDial(); 

return(1); 


ReceiveC1); 

/* post because of when done it will post a request event 
end use up one GetRequest() */ 

returnC0); /* no error in this code */ 


DoATNetCParHan) 
ABRecHendle ParHan; /* a handle to record generated by AT */ 


/* handle all events generated by appletalk 
net work. The possible events call include: */ 


Handle i temHand; 
int type; 
Rect Se 1Box; 


ifC ParHan == SendRec) 
if€ (**ParHan).atpProto.atpNumRsp > 0) 
/* here is where you would process response */ 
/* no response, the responder is out 777 */ 
else ifC ParHan == atpRec) 


GetDI temCmyW indow, КЕСИ, &type, & i tenHand, &Se1Box2; 
SetITextCitemHand, ((**ParHan).atpProto.atpDataPtr) ); 


SendResponce(ParHan); /% send responce to requester*/ 
Receive(1); /* set up for another */ 
) гешгп(0); 
Алады. 
/* clean up the frame and 916 area */ 
int error; 
97255  tempstr; 


if€ CRecSocket != 0) && Cerror = ATPCloseSocket(RecSocket) != 
noErr) ) /* for the receive socket */ 


ErrMess = “\pSomething wrong ATPCloseSocket. ”; 
NumToStringC ClongDerror, tempstr); 
Pappend(ErrMess, tempstr); 

ErrDial(); 

return( 1); 


) 
NBPRemoveC&myEnt ity); 
ifC SendRec != 0) 


/* remove from net */ 
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ATPReqCance1 (SendRec, CCBoolean)FALSE )); 
/* for send socket, async */ 


) 

ifC atpRec != 0) 
DisposHandleCatpRec); 

if myABRecord != 0) 
DisposHand1e(myABRecord); 

if€ Responce != 9) 
DisposHandle(Responce 2; 

ifC SendRec != 0) 
DisposHandleCSendRec); 

return(9);  /* good return */ 


) 
ErrDialc) 


/* dialog box with the error in it the error message is 
contained in a globalthe error dialog stays up until а mouse 
down occures */ 


Handle itemHand; 
int type; 

Rect SelBox; 
DialogPtr | errorWindow; 
WindowPtr — oldport; 
GetPortC&oldport); 


errorWindow = GetNewDialogCERRDLOG ID, NIL,, CM indowPtr2- 1); 
SetPortCerrorWindow); 
GetDItemCerrorWindow,ERRMESS, & type, & i temHand, &Se 1Box); 
Set IText( itemHand, ErrMess); 

FremeRect(&SelBox); 
GetDItenCerrorWindow,2,&type, & i temHand, &Se1Box2; 

ErrMess = “\pClick Mouse to Continue’; 

ma НИЕВИ 

do 


) while С !Button() ); 
CloseDialogCerrorWindow); 
SetPortColdport); 

return; 


/* click to go away */ 
/* make go away */ 


) 


int 
PLengthCstrPtr) 
unsigned cher *strPtr; 


/*returns the length of the pascal string*/ 
returnC (CintostrPtr{@] + 1) 5; 
/* the first byte is the length */ 


) 
PstrcopyCdest, sour) 
unsigned cher *dest, *sour; 


dest[0] = 0; 
Pappend(dest, sour); 
return(0); 


/* no string in thre */ 


PappendCdest, sour) 
unsigned char *dest, *sour; 


/* copy the ‘C’ string at sour to a P string at dest */ 
/* NOTE: the dest char array should be declared static to 
insure you don't bad results */ 
int loop; 
int dlen,slen; 
slen = Cintosour[01; /* length of string*/ 
dlen = CintOdest[0]; /* not include length byte */ 
slen = ( (dlen + slen) <= 255) ? slen : 255 - dlen; 
/* not over the stupid limit */ 
dest[0] += slen; /* new length of stuff */ 


dest += dlen; /* get to end of stuff */ 
Sour**; /* get pest the length byte */ 
dest**; /* seme */ 
BlockMove(sour, dest, Clong)slen); 

return(0); 
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/* this is the header file for 811 the good id on the dialog 


window */ 

"include "Appletalk.h^ 

"define ERRDLOG_ID 129 /* the error dialog */ 
"define DIALOG_ID 128 


"define LOOKB 1 
define DISPLAYB 2 
define SENDB 3 
define RECM 10 /* received message */ 


define MYNODE 11 /* chooser name*/ 

define ^ CNODEIS 12 /* NAME OF CURRENT NODE */ 
define CNODENUM 13 /* current device selected */ 
"define | NUMBER 14 /*no. NODES,SOCKETS on zone */ 


"define ЅЕМОМ 15 /* EDIT FIELD SEND MESSAGE */ 
define . MYNUM 17 /* THE NODE NUMBER I AM */ 
"define ЕККМЕ55 1 /* FOR USE IN ERROR DIALOG */ 
"define NIL ØL /* a nil pointer */ 


"gefine PortBUse 0х291 
#define SPConfig ФхІҒВ 
define МҮ50СКЕТ 
define  ASYNC 

define SYNC 

"define цвеҒгее 
"define useATalk 
#def ine ^ useAsync 
typedef struct  CurEntity 


— 


* Ø is on fly allocations */ 


м. QQ — CÓ 


AddrBlockCurAddrs; 
EntityName CurNeme; 
) CurEnt ity; 


MPW Format Resource File 


resource 'DLOG^ C128) ( 
(40, 22, 338, 484), 
noGrowDocProc, 
visible, 
goAway, 
0x0, 
22811, 

“APPLETALK TEST DIALOG” 

7 


resource “0100” (129, “еггог”) ( 
(78, 64, 218, 404), 
dBoxProc, 
visible, 
goAway, 
8x0, 
13469, 
*AppleTalk Error Messages" 


); 


resource 'DITL^ (22877) ( 
/* array OITLarray: 17 elements */ 
/* (1) */ 
(248, 44, 282, 135), 
Button ( 
enabled, 
“LOOKUP” 


); 
/* (2) */ 
(247, 187, 281, 278), 
Button ( 

enabled, 
“DISPLAY” 
/* (3) */ 
(247, 326, 281, 417}, 
Button ( 

enabled, 

*SEND^ 


); 
/* [4] */ 
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(8, 16, 32, 112), 

StaticText ( 
disabled, 
“DEVICE NAME: ^ 


); 
/* [5] */ 
(64, 16, 80, 152), 
SteticText ( 
disabled, 
“RECIEVED MESSAGE: ” 


); 
/* [6] */ 
(120, 17, 136, 153), 
StaticText ( 
disabled, 
*SEND THIS MESSAGE : ^ 


/* (7) */ 
(160, 224, 176, 368), 
StaticText ( 

disabled, 

«8 OF DEVICES ON МЕТ: * 


/* (8] */ 
(186, 16, 202, 192), 
StaticText ( 

disabled, 

“CURRENT DEVICE SELECTED: ^ 


» 

/* [9] */ 

(208, 16, 225, 122), 

StaticText ( 
disabled, 
“CURRENT NAME:" 


}; 

/* [10] */ 

(48, 160, 96, 416), 

StaticText ( 
disabled, 


StaticText ( 
disebled, 


); 
/* (11) */ 


(9, 120, 34, 297) ; ЛҒ 
Staticlext ( E DEVICE * : 
j д 
“Mac's Noe » /* LIT] */ 
ы (8, 379, 32, 458), 
à StaticText 
/* 112] */ 
(208, 128, 232, 392), disebled, 
StaticText ( 
disebled, ) 
); ); 
/* [13] */ 


resource 'DITL^ (13469) ( 


(186, 197, 202, 293), /* array DITLerray: */ 


StaticText ( 


/* (1) */ 
disabled, (8, 190, 120, 331), 
, StaticText ( 
: disabled 
јх [141 */ и , 
(150, 376, 176, 416), | Error Message. 
StaticText ( : 
/* [2] */ 
disabled, (166, 75, 189, 242), 
ч StaticText ( 
ү: TT disabled, 


(104, 160, 152, 416), Click Mouse to continue. 


EditText ( ) 
disabled, y; 


); 
/* (16) */ 
(8, 383, 32, 375}, é 
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C Workshop 
CDEV Extends Control Panel 


The new control panel that comes with System 4.1 is exten- 
sible. You can write a code resource called a ‘cdev’ to add 
functions to the control panel. The process is not difficult, and it 
offers a number of interesting possibilities. 

What I had in mind for this project was to write a fairly simple 
cdev, just to test the waters. Having just acquired a Macintosh II, 
I also wanted to explore some of the sound generation capabili- 
ties. The result is Monkey, an amusing addition to the control 
panel. Although this particular cdev will only work on a Macin- 
tosh II (because it calls the Mac II's sound routines), the tech- 
niques shown here will work for more generalized cdevs as well. 

The Control Panel 

Figure 1 shows the new Control Panel with the General panel 
displayed. The panel allows choosing the Desktop pattern, set- 
ting the rate of insertion point blinking, setting the time, and 
more. Some other standard panels allow setting keyboard op- 
tions, sound options, and display options. 

By writing your own cdev, you can add a new icon to the 
scrollable list that appears on the left edge of the Control Panel. 
In Figure 1, you can see the icon for the Monkey cdev at the 
bottom. Clicking on an icon selects it, and the Control Panel 
displays various controls, depending on the item list contained in 
the corresponding cdev. Figure 2 shows how the Control Panel 
appears when Monkey is selected. Clicking on the picture of a 
monkey causes the Macintosh II to generate the a monkey 
screech sound. 

How It Works 

When the user opens the Control Panel, it scans the System 
Folder for all resource files of type “cdev’. When it finds one, it 
loads the icon and the file's name and adds it to the icon list. After 
all the cdevs are loaded, the General icon is selected and the 
standard controls are displayed. The Control Panel then calls the 
cdev with various event messages, indicating which items the 
user has clicked or dragged, enabling the cdev to track its 
controls. 

A cdev file must contain eight resources: 

* cdev - acode resource 

* mach - some data that indicates which machines the cdev is 

compatible with 

* DITL - a standard Dialog item list 

• nrct - some data that defines the number of rectangles needed 

for the cdev's display, and their sizes. 

* ICN# - a standard icon with mask 

* BNDL - a standard bundle resource 

е FREF - a standard file reference resource 

е An owner resource, that must be a unique four—character 

identifier, just like the ones used for applications. The 
Monkey cdev uses the type *'mOnk'. 
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Fig. 1 Adding our own control functions 

With the exception of the owner resource, all the resources 
should have the same ID number, -4064. The owner resource ID 
depends on how the BNDL is structured, and is usually zero. 

The nrct and mach Resources 

These two resources are unique to cdevs, and require some 
more detailed explanation. The nrct type is a list of rectangles. 
The first word of the resource is the number of rectangles in the 
list. It is followed by eight bytes for each rectangle, which 
describe the top, left, bottom, and right boundaries. For each 
rectangle defined in the nrct, the Control Panel clears out some 
white space in its window, and draws a frame around it. The nrct, 
along with the DITL, define the look of the cdev panel. 

The mach resource type consists of two words. The first is 
called the Softmask, and is compared to the global variable 
ROMSS to determine which toolbox features are available (such 
as Color Quickdraw). The second word is called the Hardmask, 
anditis used to determine which hardware features are available. 
The values of these masks determines on which machines the 
cdev will appear. Table 1 shows some possible settings. 

The cdev code 
Listing 1 shows the code used in the Monkey cdev, written in 


LightspeedC. The main function is declared as: 
pascal Handle 
main(message, item,numI tems, СРапе110,ер,сдеу5іогаде, CPDialog) 


int message, item, пит tems, СРапе110; 
EventRecord *ep; 

Hendle cdevStorage; 

DialogPtr CPDialog; 


Message is a number that tells the cdev what event just took 
place. Monkey only responds to three types of messages: ini- 
tDev, which means “do your initialization”; closeDev, which 
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means “dispose of any allocated storage and close up shop”; and 
hitDev, which means “the user clicked on an item”. 

For initDev, Monkey just allocates 16 bytes of storage, and 
returns the handle in cdevStorage. Monkey does not use this 
storage, but the Control Panel wants to see a valid handle. For 
closeDev, Monkey releases the 16 bytes of storage, and clears the 
cdevStorage variable. For hitDev, Monkey loads the ‘snd ° 
resource with ID# 4 (the monkey screech),and then calls the 
Macintosh II Sound Manager routine SndPlay to generate the 
sound. Since there is only one item, the DoHit routine does not 
have to determine which item was clicked on. If there were more 
items, the DoHit routine would have to subtract numItems from 
item to determine which item in its DITL was clicked. This is 
because the cdev's DITL is appended to the Control Panel's 
DITL. 

Compiling the cdev in LightspeedC 

Creating the Monkey cdev is fairly straightforward in Light- 
speedC. First use RMaker to compile the necessary resources, as 
given in Listing 3. Create a new project called MonkeyCdevP, 
and set the project type to a code resource of type cdev. Enter 
Listing 2, and save itas SoundMgr.h, in the same folder with your 
other Macintosh header files. Add the Mac Traps library to the 
project. Enter Listing 1, save itas MonkeyCdev.c and add it to the 
project. Then build the code resource (select Build Code Re- 
source from the Project menu). Save it as Monkey. Finally, use 
ResEdit to set the creator type to mOnk, and set the bundle bit. 
Now drag the finished cdev into the System Folder, open the 
Control Panel, and make the monkey screech! 

A Note About the Resources 

I didn't actually use RMaker to create the resources for the 
Monkey cdev. I created them with ResEdit, and then used a 
shareware resource decompiler called ResDecomp, by Robert 
Comer, to create the RMaker source code for publication. To 
save yourself some typing, you may want to create your own 
ICN# and PICT resources using ResEdit, rather than enter all the 
hex code for them. Just be sure to give them the correct ID 
numbers, and make them purgeable. 

By the way, the monkey picture was originally taken from a 
clip art disk called WetPaint, put out by Dubl-Clik software. I 
modified it some, but I like to give credit for these things. 


Fig. 2 Our Monkey Squeek! 


/* Monkey CDEV 

* by Jan Eugenides 
* 6/6/87 

x 


* Ап example of adding а function to the 
* Control Penel, апа using the Macintosh II's 
* SndPlay routine 


8include «MacTypes.h? 

*include «pascal.h? 

*include <MemoryMgr .h> 

*include <OSUti].h» 

include <ToolboxUtil.h» 

#include <DialogMgr .h> 

*include <EventMgr .h> 

®include <SoundMgr .h> 

/*First define some needed constents*/ 


hitDev, 
closeDev, 
nulDev, 
updateDev, 
deActivDev, 
keyEvtDev, 
macDev 


М 
Handle InitStorage(); 


/*This is main routine, entry point for the CDEV*/ 


pascal Handle 
main (message, item, numI tems, CPanel ID, ep, cdevStorage, CPDialog) 
int message, item,numI tems, СРапе110; 

EventRecord зер; 

Hendle cdevStorage; 

DialogPtr CPDialog; 

if(message == macDev)return( (Handle) 1); 

И 

аи 


cese initDev: /*Init messege received, 
allocate some storage*/ 

cdevStorage = InitStorage(); 
if (cdevStorage )DoHi tC ltnumI tems, numI tems, CPDialog); 
break; 

case closeDev: /*Close message received, dispose of 

storage*/ 

DisposeStorageCcdevStorage); 
cdevStorage = (Handle aL; 
break; 

case hitDev: /*User clicked an item, handle it*/ 
DoHitCitem,numI tems ,CPDialog); 
break; 

) /*end switch*/ 

) /*end else if*/ 
return(cdevStorage); 


Handle InitStorage() /*ultra-simple storage allocation*/ 
/*The storage is not used in this example*/ 
Лашын. 


DisposeStorage(h) /*Release our storage area*/ 
Handle h; 


DisposHandle(h); 


DoHitCiten,nunItems, CPDialog) /*Handle a click on one of 
our items*/ 


int  item,numItems;  /*This example has one item, so it's*/ 
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DielogPtr CPDialog; /*very simple*/ 00000000 4B004298 000ҮА0031 0066007С 
00Ү480031 0066007С 00A80000 00000048 
Handle soundH; 00420000 08ҒС0002 O1FFFOFF 0008ЕС@@ 
O203FFFC ҒҒ0008ҒС 000206АА ААҒҒ0008 

soundH = GetResource(‘snd ',42;/*there is а space after snd */ ҒС00020Ғ FIFTFFOQ 08ҒС0002 QOAAAABFF 
if CsoundH ) 0008ҒС00 020FFFFF ҒҒ0008ҒС 00040ВҒҒ 
SndP lay(@L,soundH, TRUE); /*play the monkey screech*/ АА800008 ҒС000406 00ҒҒ8000 06ҒА0002 
2AB00006 ҒА00023Ғ 800006ҒА 0002 1АС0 

00040200 00ҒЕҒ000 02 17С000 08030003 


* Resources for Monkey cdev FF8üFE08 021ACOO0 0B03000F Ø 1Е0ҒЕ00 
02 1ҒС000 08090Ғ0С 007ҒС000 001ҮС000 
MonkeyCdevP .rsrc 0809 1ҒҒ9 С7ВҒҒ000 00 1Ғ4000 08093AF7 


(00100100100100100100100 ҒҒОАВ800 00 1АС000 08007ҒЕЕ 3COFFCOÓ 


T 00 IFCØØØ 0BOOGAEC 992ЕАС00 00 1АС000 
Туре ICN% = GNRL | ØBØ97FCD DBB7FCOO 00 17С000 08096АС0 
‚74064 (32) ;; attributes -> Purgeable 9986ACOO 00 1АС000 08097ҒСС 0037ҒС00 


: 00 1ҒС000 08096АС6 00668800 00 1АС000 
00000000 0000ҒЕ00 0003ҒҒ80 000Ғ01Е0 0В093ҒС4 ҒҒ27Ғ800 001-4000 0B0038C1 


0Ғ9С007Ғ IFFOCTBF ЗАРТРРОА TFEESCOF FF87FFCO 00 1АС000 0809 1ҒЕЗ D7CFFFFB 
6AC690066 SFC4FF27 3BCIFF87 IFESD7CF 08090036 3C78080F CO178000 0809003C 
gFOTFFED 09363078 003С0030 00 1DFFBO 00305555 FO 148000 08000010 FFBOOOOO 
0000С385 000С4230 00077Е75 00 1Ғ00Е0 103-8000 08090000 C3B55555 5E2A8000 
0030ҒҒ05 0078ҒҒ08 00F57555 01Е28000 0809000С 42308080 878-8000 08030007 
03057555 07Е8Е080 00Е5Е555 ІҒҒҒВ000 ТЕТ5ҒЕ55 02ЕА8000 080200 1Ғ OOEOFEQO 
OFOFFFFF IFFFFFFF SFFFFFFE TFFFFFFF 64020078 FFFDO8B2 3F80000A 0200F575 
TFFFFFFE 7FFFFFFF 7FFFFFFE 7FFFFFFF FD55025A 80000402 0 ДЕР 0002 1Е8 

EIL КЕ 


QFTFFFFD SO3FFFF8 OO3FFFFD @@1ЕЕЕЕЙ FOFD8002 8F80000A 0200Ғ5Ғ5 FD55025F 
OOOFFFFS SOOFFFFO OOOTFFFS 00 IFFFEO 00000А02 1FFFBOFD 00020700 000А023А 


OOSFFFDS 007ҒҒҒ08 00ЕЕЕ555 0ІҒЕҒ 00 AF35FD55 02570000 04027 , 
g3FFF555 QTFFFO80 OFFFF555 ІҒҒҒВ000 liii. Res 82777C75 Ғ0550257 00000402 


FFF860FD 00020300 000А02ЕА BOTbFD55 
02570000 0809ҒҒЕй 6080ҒЕ80 80830000 
080900С0 7557FFD5 55570000 0809ҒҒ80 
COQT3BCO 00030000 0809ЕҒ00 055ЕЗ5Ғ5 
55570000 08097Е00 С8 1С38Е8 08080000 
08073800 05583570 5557ҒҒ00 08070000 
0030328С 0003ҒҒ00 08070001 05707550 
59557ҒҒ00 08070001 80Е0688Е 8083ҒҒ00 
08070001 D560755F 5557ҒҒ00 08070003 
80С06А38 0003ҒҒ00 08070003 05С0055В 
5557ҒҒ00 08070003 0980С881 880ВҒҒ00 


Table 1: Sample mach Settings 


Softmask Hardmask Function 


$0000 $FFFF call cdev to determine whether it should show up 
$FFFF $0000 show up on all machines 


Type FREF 


, 4064 (32) ;; attributes -? Purgeeble 
cdev 0 


Type BNDL 
, 4064 (32) ;; attributes -» Purgeable 
monk 0 


08070007 55800571 D557FF00 08070006 
0300Е2Е0 (003ҒҒ00 08070007 57000560 
0557ҒҒ00 0807000Е 860 188С0 6083ҒҒ00 
0807000Ғ 560 10560 7556ҒҒ00 08070010 
0С01А880 3006ҒҒ00 0807001Ғ ҒС0ІРЕ80 
IFFEFFØØ 0807003Ғ Ғ80ЗҒҒ00 ІҒҒЕРҒ00 
08090077 78037700 0Ғ760000 08090 IFF 
Ғ80ТЕҒ00 0ҒҒЕ0000 0809ТҒЕА BOFEABOF 
FEAE0000 SBOOFFFF FBFFFF IF ҒҒҒЕ0000 


ICN" 08090000 FBDDDF1D 000Е0000 OBOOFFFF 
0 -4064 FOFFFF IF ҒҒҒЕ0000 0BOOTFFF E1FFFEQF 
FREF ЕҒҒС0000 FF 
0 -4064 
Туре mOnk = GNRL 
Type DITL m 


‚74064 (32) ;; attributes -> Purgeable 


PicItem 
1 128 76 194 
-4064 


StatText Disabled 
77 133 93 206 
Click Me! 


Type PICT = GNRL 
‚74064 (32) ;; attributes -> Purgeable 


‚Н 
03850000 00000048 00421101 01000А00 
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, 74064 (32) ;; attributes -> Purgeeble 
.H 
1C4D6F6E 68657920 63646576 20627920 
4А616Е20 45756765 6E696465 73 


Type nrct = GNRL 
, -4064 


‚Н 
900 1FFFF 00570066 00СЕ 


Type mach = GNRL 
‚74064 (32) ;; attributes -> Purgeable 


Н 
ЗҒЕР2000 


Bit Map Graphics 


A FatBits Editor & Clipboard егі in C 


Editing BitMaps 

At the heart of high-speed graphics on the Macintosh is the 
bitMap structure. Data stored in bitMaps and pushed around with 
CopyBits form the basis for much of the drawing that occurs on 
the Macintosh screen. Being able to create bitMaps for inclusion 
into a program and being able to eidt such things is of great 
importance in many applications. MacPaint, and offspring, offer 
away of doing this which is less than ideal for small bitMaps. The 
following program sets up a bitMap, allows the user to edit the 
bitMap in a manner similar to FatBits in MacPaint, then writes 
out the bitMap data in hexadecimal in a format suitable for 
RMaker. 

There are numerous variations possible. With a call to 
SFGetFile(), followed by some Resource Manager calls, the user 
could open up any resource file and then open up any of several 
types of resource based on bitMaps, such as ICONS, and РАТ 
and edit them. It would also be possible to edit objects such as 
ICN#’s and CURS’s, which consists of slightly more compli- 
cated data structures. With some modification, this program 
could also form the basis for a FatBits feature in a bit-mapped 
graphics program. One could also give the user a dialog box with 
which to set the size of the desired bitMap, initialize a data 
structure to hold the requested bitMap, then let the user edit it. 
When done, the program would then dump the bitMap out in hex, 
which could then be put into a program as data for a CopyBits call 
to draw figures on the screen. Instead of writing the bitMap to a 
disk file, the edited bitMap could be added to a resource file in an 
appropriate format. It wouldn't take much work (in principle at 
least!) to reproduce the ICON, ICN#, РАТ, and CURS editing 
functions of ResEdit ina much smaller program. Be careful when 
fiddling around with resource files, Scott Knaster's "How to 
Write Macintosh Software," (Hayden Books) has some invalu- 
able tips and hints. This program was originally written over a 
year ago with that in mind, but I kept crashing the system with my 
Resouce manager calls. I'm almost brave enough to give it 
another try after reading Knaster's book. 

The Bit Map Object 

In what follows, we will be working with a bitMap whose 

number of rows and columns are ‘nRows’ and ‘nCols’ respec- 


tively. In C we represent the BitMap structure as 
struct BitMap ( 


Q0Ptr baseAddr; 
short rowBytes; 
Rect bounds; 

); 

typedef struct BitMap; 


*baseAddr" is a pointer to the BitMap’s raw data. “rowBytes” 
is the number of bytes in each row of the bitMap. There must be 
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= BitMap Editor 


Fig. 1 Our bit map editor at work 


an even number of bytes in each row, so we have to pad BitMaps 
whose width is not a multiple of 16 bits. To calculate rowBytes 
from the number of columns in a BitMap, we use the following 
formula: 


rowBytes = ( (nCols-1)/16 + 1 2 * 2; 


The size needed to store the data for the BitMap is then 
rowBytes*nRows. 

“bounds” is a rectangle which determines the QuickDraw 
coordinates put onto the BitMap. The coordinates of the upper 
left corner of bounds become the coordinates of the upper left 
comer of the BitMap. Also, 


bounds .bottom = bounds.top + nRows; 
bounds .right = bounds. left + nCols; 


For simplicity, I assign bounds.top = bounds. left = 0. 

Once we know the size of the desired BitMap in terms of 
nRows and nCols, we know how much memory to allocate and 
how to fill in the BitMap data structure. The routine getMap() 
does these things. To alter the size of the BitMap, and/or its initial 
contents alter getMap(). For this example, I build a 32 x 32 
bitMap, then load in ICON #1 (from the System file), which is the 
"NotelIcon' used in the NoteAlert. Since I call DetachResource() 
on the handle I get, any editing done on the ICON will have no 
effect on the actual resource. In a real-life situation, you would 
probably want to make a copy of the ICON, so as to not clobber 
something which might be in use by a desk accessory. 

Editing the Bit Map 

After the BitMap is called, we call editMap() which sets up a 
window for editing the BitMap then goes into an event loop. 
Mouse clicks are passed to editBits(), which is the heart of the 
program. Activate events are handled in a very simplistic way 
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which would need to be beefed up to support multiple windows. 
Update events for the window are processed by doUpdate(), the 
other routine of interest. Since there are no other windows with 
which to generate update events (after the first one), if the user 
hits the backspace key, an update event is generated, just to make 
sure doUpdate() works correctly after the bitMap has been 
edited. 

editBits() takes a BitMap and a window pointer. It assumes 
that the BitMap is currently displayed in the window and that the 
mouse has just been pressed within the window. Itthen calculates 
where the mouse was pressed and what bit of the BitMap is 
represented by the location of the mouse click. It then accesses 
the BitMap through GetPixel() to determine if that bit is on or off. 
If it was off, the routine tracks the mouse and turns on every bit 
it runs across until the mouse is released. If the first bit was 
already on, it turns contacted bits off. As the mouse moves 
around, the routine constantly calculates what bit in the BitMap 
is being hit. If the current bit needs to be changed, it is changed 
as is the rectangle that represents it in the window. 

When the close box on the window is clicked, the program 
calls SFPutFile() to get a destination file, then outputs the 
contents of the bit map in an RMaker format which could then be 
used to generate a resource with the BitMap data. The resource 
format is one that I made up. It consists of two two-byte integers 
representing the the number of rows and columns, followed by 
the (possibly padded) BitMap data, one row on each line. It would 
be quite easy to modify this code to put out data for an ICON, or 
ICN#, or other existing resource type. As mentioned earlier, the 
edited bitMap could also be put directly into a resource file. 

The FatBitsFeature 

To implement a FatBits feature into a graphics program, it 
would probably be easiest to copy the selected bits to a fresh 
BitMap, let the user edit them, then copy them back into the 
document. Alternatively, one could edit the larger BitMap di- 
rectly, but modify editBits() to edit only some sub-rectangle of 
the BitMap and to deal with the fact that the upper left hand corner 
of what is being edited may not be the (0, 0) pixel of the BitMap, 
and that the boundaries of the window may not coincide with the 
boundaries of the BitMap (this last item is important when 
tracking the mouse). 

To edit ICN#’s, which consist of two ICON’s, I would put 
each ICON into a separate BitMap, and then put the two BitMaps 
in side-by-side FatBits in a common window. Then mouse 
tracking is a little trickier, you have to figure out which ICON the 
mouse was pressed in and the upper left corner of the second 
ICON will not be in the upper left corner of the window. Similar 
thingscan be said of CURS’s, with the additional task of figuring 
our how to deal with the hotSpot. 

Add this to the articles on displaying MacPaint files (by Gary 
Palmer), and drawing with the mouse (by Bob Gordon) from the 
May '87 issue, and Joel West's printing article from March, 
throw in some mechanism for scrolling and you have just about 
all of the technology needed to write a Paint program. 


8include <abc.h? 
®include <MacTypes.h> 
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ttinclude 
include 
include 
include 
include 
include 
#include 
#include 


Ptr 


def ine 
#def ine 


«QuickDraw .h» 
«EventMgr .h> 
<WindowMgr .h? 
<DialogMgr .h> 
<MemoryMgr .h> 
«ResourceMgr .h? 
«StdF i lePkg.h» 
«FileMgr.h? 


ge tMap(); 


PixelWidth 4 
PixelHeight 4 


WindowRecord wRecord; 


WindowPtr 


theWindow; 


EventRecord theEvent; 


short 


cher 


char *hexDigits = *2123456789ABCDEF ^, 
“\Ptype BMAP=GNRL\r, 128 Nn ^, 
“\P.I ;; nRows..\r’, 

“\P.I ;; nCols..\r’, 


*stringl = 
*string2 = 
*string3 = 


nRows, 
nCols; 
theString[256]; 


*string4 = “\P\r’, 


¥stringS = 


mainc) 
( 


Ptr 


theData; 


initialize(); 
theData = getMap(); 


if С theData NEQ NULL ) ( 
editMap( theData ); 
writeMapC theData ); 


) /* main 


i 


ыы 


InitGraf С &thePort ); 


Ini tFonts(); 
Ini tWindows( ); 
Ini tMenus(); 
TEInitO; 
InitDialogs C NULL ); 
InitCursor(); 

) /* initialize */ 


/* 


Allocates memory for the requested bitmap 


*/ 
Ptr 
ыды 


register Ptr theData; 
register short i; 
Handle tempHandle; 


Size 


theMapS ize; 


nRows = nCols = 32; 


tempHandle = GetResource С ‘ICON’, noteIcon 2; 
if € tempHandle EQ NULL ) 


return NULL; 


DetachResource С tempHandle ); 


HLock ( tempHandle ); 
return *tempHandle; 


) /* getMep */ 
editMap С theData ) 


«\Р.Н ;; the BitMap data itself. Ar^; 
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C theData; 


WindowPtrwWindow; 
BitMap | theBitMep; 
Rect wRect; 


Boolean done; 
short thePar t; 
char theChar ; 


/*Create window to display BitMap in FatBits*/ 

SetRect С &wRect, 50, 50, 50*nCols*PixelWidth, 
50*nRows*PixelHeight ); 

theWindow = NewWindow С &wRecord, &wRect, 
“\PBitMap Editor”, TRUE, 4, - 1L, TRUE, OL 5; 


/*initialize the BitMap record using the theData */ 
theBitMap.baseAddr = theData; 

theBitMap.rowBytes = € ((пбо15 - 1) / 16) + 1) * 2; 
SetRect (С &theBitMap.bounds, Ø, Ø, nCols, nRows ); 


/* process mouse until user dismisses window */ 
done = FALSE; 
do ( 
if € GetNextEvent С everyEvent, &theEvent 2 2 ( 
switch С theEvent.what 2 ( 
case mouseDown: 
thePart = FindWindow С theEvent .where, 
&wWindow ); 
if С window EQ theWindow ) ( 
switch С thePart ) ( 
case inContent: 
editBits С theWindow, &theBitMep ); 
breek; 
case inGoAway: 
if С TrackGoAway С wWindow, 
theEvent.where ) 2 ( 
HideWindow С wWindow 2; 
done = TRUE; 


) /* switch С thePart ) */ 
) /* if wWindow EQ theWindow */ 
break; 


case keyDown: 

theChar = theEvent . message; 

switch С theChar ) ( 

cese BS: 
/* force update event */ 
EreseRect С &theWindow->portRect ); 
InvalRect С &theWindow->portRect 2; 
break; 

case RETURN: 

case ENTER: 
done = TRUE; 
break; 

default: 
SysBeep(2); 
break; 


break; 


case activateEvt: 
SetPort ( theEvent.message ); 
break; 


case updateEvt: 
doUpdate С theWindow, &theBitMap ); 
break; 
) /* switch С theEvent.what ) */ 
) /* if GetNextEvent() */ 
) while € NOT done ); 


) /* editMap */ 
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doUpdate С badWindow, theBitMap ) 
WindowPtr badWindow; 
"nd *theBitMap; 


register char *theData; 
register short j, k, rowBytes; 
register char  tempChar; 

short i; 

GrafPtr savePort; 

Rect pixelRect; 

GetPort ( &savePort ); 

SetPort ( badWindow ); 


SetRect С &pixelRect, 1, 1, PixelWidth, PixelHeight 2; 


theData = theBitMap-?beseAddr ; 
rowBytes = theBitMap->rowBytes; 
BeginUpdate ( badWindow ); 
/* Draw grid dots.. */ 
for Ck = 0; k <= nRows; к++ ) ( 
MoveTo С 0, k*PixelHeight 2; 
for CisnCols; i >= Ø; i- 2 ( 
Move С PixelWidth, 0 ); 
Line (0,0); 


/* Fill in contents of current BitMap */ 
for (C ј = 0; j < nRows; ј++ ) ( 
for С i = 0; i < rowBytes; із ) ( 
tempChar = theDatalitj*rowBytes]; 
for (Ck = 0; k « 8; kt* ) ( | 
if С tempCher БАМ 9x80 ) 
PaintRect С &pixelRect 2; 
OffsetRect С &pixelRect, PixelWidth, Ø ); 
tempChar = tempChar << 1; 
) /* for (k) */ 
) /* for (1) */ 
OffsetRect ( &pixelRect, - 
rowBytes*8*P ixelWidth,PixelHeight 2; 
) /* for Cj) */ 


EndUpdate С badWindow ); 
) /* doUpdate */ 


editBits C bitWindow, theBitMap ) 
WindowPtr bitWindow; 
nu *theBitMap; 


register char *theData; 
GrafPtr myPort; 
short theError ; 
Point mouseLoc; 
Rect pixelRect; 
short vHit, hHit, 
dh, dv, 
BorW; 
Boolean done; 


/* rectangle for drawing “Fat” pixel.. */ 
SetRect С &pixelRect, 1, 1, PixelWidth, PixelHeight 2; 


/* make a register copy of theBitMap-»baseAddr */ 
theDeta = theBitMap-»baseAddr; 

/* get memory for the GrafPort */ 

myPort = (GrafPtr) NewPtr С SIZEOFCOrafPort) ); 
if С MemError() ) ( SysBeep(2); return; } 

/* Initialize “myPort” and install *theBitMap^ */ 
OpenPort С myPort ); 

SetPort С myPort ); /* Is this necessary? */ 
SetPortBits С theBitMap ); 


/* 
mouse location is recorded and tested. If it is 
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in the active area, drawing begins, else return. 
x 


SetPort С bitWindow 2; 


GetMouse ( &mouseLoc ); 
dh = С hHit = € mouseLoc.h )/PixelWidth ) * PixelWidth; 


dv = С vHit = € mouseLoc.v )/PixelHeight ) * PixelHeight; 
ifCvHit < 0 OR vHit >= nRows OR hHit < Ø OR hHit >= nCols){ 


/* mouseDown was not in active area */ 
ClosePort С myPort 2; 
DisposPtr С myPort ); 
SysBeep(2); 
return; 


SetPort С myPort ); 

BorW = GetPixel C hHit, vHit ) ? patBic : patCopy; 
PenMode С BorW 2; 

SetPort € bitWindow 2; 

PenMode С BorW 2; 


/* The drawing begins... */ 
done = FALSE; 
do ( 
if € NOT Button() 2 
done = TRUE; 
else ( 
GetMouse ( &mouseLoc ); 
dv = € vHit = € mouseLoc.v )/PixelHeight ) * 
PixelHeight; 
dh = € hHit = € mouseLoc.h )/PixelWidth ) * 
PixelWidth; 
if € vHit < 0 OR vHit >= nRows 
OR hHit < Ø OR hHit >= nCols ) 


else /* the mouse is in the drawing area.. */( 
SetPort С myPort 2; 
/* Does hit bit need to be modified? */ 
if € BorW EQ CGetPixelChHit,vHit) 
2 patBic : patCopy) 2 ( 
/* First, modify the *theData^ 
through "myPort^ */ 
MoveTo C hHit, vHit 2; Line С 0, 0); 
/* Then modify the (visible) window */ 
SetPort С bitWindow 2; 
OffsetRect С &pixelRect, dh, dv); 
PaintRect ( &pixelRect ); 
OffsetRect С &pixelRect, -dh, -dv); 
) eise 
/* For next time through the loop */ 
SetPort С bitWindow 2; 


) 
) while С NOT done 2; 
SetPort С bitWindow 2; 
PenMode С patCopy ); 
ClosePort С myPort 2; 
DisposPtr С myPort 2; 


) /* editBits */ 


/* 
This routine writes out contents of the bitMap in 
hexadecimal in a format which RMaker will take. 
*/ 
writeMap С theDate ) 
oo unsigned char *theDate; 


register i, j, rowBytes, 
SFReply theReply; 
short theErr, 


fPethNun; 
long writeSize; 
unsigned cher —theCher, 
oneWord([2]; 
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SFPutFile С 0х00640064, "NPSave Data File А$..”, 
“\PUntitled”, NULL, &theReply2; 

if € NOT theReply.good ) 
return; 


if С theErr = FSOpen С theReply.fName, 
theReply.vRefNum,&fPathNum 2 2 { 

if С theErr NEQ fnfErr ) 
return; 

if С theErr = Create С theReply.fName, 
theReply.vRefNum, ‘BmEd’, ‘TEXT’ ) D 
return; 

if С theErr = FSOpen С theReply.fName, 
theReply.vRefNum, &fPathNum ) ) 
return; 


) 

if € theErr = SetEOF С fPathNum, ØL ) ) 
goto err; 

if CtheErr = SetFPosCfPathNum, fsFromStart, 012) 
goto err; 


/* write type end ID number.. */ 

writeSize = string1{@]; 

if CtheErr = FSWrite C(fPathNum, &writeSize, stringi+1)) 
goto err; 


/* write number of rows.. */ 
writeSize = string2[01; 
if CtheErrzFSWrite CfPathNun, &writeSize,string2* 12) 
goto err; 
NumToString С Clong) nRows, theString 2; 
writeSize = theString(£]; 
if CtheErr=FSWrite CfPathNum, &writeSize, theStr ingt 12) 
goto err; 
writeSize = string4(0]; 
if (theErrsFSWriteCfPathNum, &writeSize, str ing4+1)) 
goto err; 


/* write number of cols.. */ 

writeSize = string3[2); 

if CtheErr=FSwWr iteCfPathNum, &writeSize, str ing3+ 12) 
goto err; 

NunToString С (long) nCols, theString ); 

writeSize = theString(9]; 

if CtheErrzFSWriteCfPathNum, &writeSize, theString+ 12) 

goto err; 

writeSize = string4[01; 

if CtheErrsFSWriteCfPathNum, &writeSize,string4* 12) 
goto err; 


rowBytes = С С ncols - 1) / 16+ 1) * 2; 
writeSize = ѕігіпд5 (01; 
if (theErr=FSwWr iteCfPathNum, &writeSize, str ingd+1)) 
goto err; 
for Ci = 0; i < nRows; i++ ) ( 
writeSize = 2; 
for С j= 0; j < rowBytes; j++ ) ( 
theChar = theDatali*rowBytes+j 1; 
oneWord[1] = hexDigits [ theChar БАМ ØxøF 1; 
oneWord[8] = hexDigits [ theChar >> 4 1; 
if CtheErrzFSWriteCfPathNum, &writeSize, oneWord)) 
goto err; 


writeSize = string4(0]; 
if CtheErr-FSWriteCfPathNum, &writeSize, string4+1)) 
goto err; 


riteSize = зігіп(4101; 
f CtheErr=FSWriteCfPathNum, &writeSize, str ing4+1)) 
oto err; 
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/* 
I hate goto’s but seemed slickest way to do 


what I wanted with minimal effort. 
x 


err: /* close the file and return */ 
FSClose С fPathNum ); 
return; 


) /* writeMap */ 
/* "definitions to make life easier and C more readable */ 


/* Inside Macintosh "defines not іп MacTypes.. */ 
typedef short INTEGER; 
typedef long LONGINT; 


/* Constants */ 
def ine NULL ØL 


/* Logical Operators */ 
"def ine NOT ! 

"def ine AND && 

def ine OR | 

#def ine MOD g 
#def ine EQ = 
#def ine NEQ | 
tidef ine bAND & 
“define bOR | 
def ine bXOR а 


/* Misc Operators */ 
"define 512Е0Е (х) Clong2sizeof (x) 


/* Math things */ 
define abs(x) (CG0«022-60: G0) 


/* these are defined in LightSpeed'/s math.h 
define PI 3.14159265358979323846 

"define E 2.71828 182845904523536 

*/ 


/* special character codes.. */ 
def ine CR 0x0D 

define RETURN CR 

define CLOVER 0x11 

define TAB 0x09 

define BS 0x08 


"define ENTER 0x03 
"define APPLE 9x14 
"define SPACE — 0x20 
def ine DIAMOND бх 13 
Comments on Past Issues 

Several things in the last few months of "Letters" and 
"Mousehole Report" departments have caught my eye and 
seemedin need of acomment or two. I have also had a bug/feature 
of the dialog manager brought to my attention in the form of an 
annoying side-effect in one of my ShareWare programs. 

In the February '87 MacTutor, there was a letter from Jean- 
Michael Decombe that came complete with a couple of very 
handy routines. His method for writing to the data fork of the 
current application is much slicker than what I have been using. 
His routine for zooming rects is also pretty handy, with a couple 
of caveats. According to IM, p. 1-282, thou shalt not change апу 
regions of the Window Manager Port, else "overlapping win- 
dows may not be handled properly." I think his call to InitPort ( 
deskPort ) violates that commandment. Also, he returns the 
wMgrPort's pen to what we all expect it should be, which seems 
a bit dangerous. I use the following: 
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GetPort С &sevePort 2; /* get current port */ 
GetWMgrPort С &deskPort 2; /* get wMgrPort */ 

SetPort (С deskPort 2);  /* make it ‘thePort’ */ 
GetPenState ( &savePen 2; /* save pen character */ 
PenMode С notPatXor 2; /* modify pen for our needs */ 
PenPat С &gray 2; 


/* zoom those rects.. */ 


SetPenState С &savePen 5; /*retore penState*/ 
SetPort С savePort 2;  /* restore original port */ 


Thanks to Jean-Michael for a couple of otherwise great 
routines. 

In the Mousehole Report of that same issue, “Beaker” asked 
for a “TE TextBox routine’ that does not share the inefficiencies 
of the ROM routine. I wrote a portable “Show Clipboard” 
function which does its own word-wrapping which will probably 
fit the bill, with minor modification, shown in the next few pages. 

In the May '87 MacTutor, there was a commentary from 
"Zenomorph" concerning disk interleaving on the Mac II. Itis my 
understanding that SCSI disks have to be interleaved on the Mac 
because they tend to send information faster than the Mac can 
keep up with for more than a sector at a time. Floppy drives are 
apparently much slower and don't need to be artificially slowed 
down by interleaving. Thus it is not surprising that a Mac, a Mac 
SE and a Mac II can all read the same floppies. Am I off track 
(pardon the pun)? Has anyone tried running a SCSI drive off of 
a Mac, Mac SE and a Mac II? Will a SCSI drive intended for a 
Мас+ automatically change its interleaving if reformatted on an 
SE or a II? 

In the June '87 issue, “Chief Wizard” responds to a question 
concerning _SystemTask. He states that _SystemTask handles 
blinking the cursor. While this is true, indirectly, of dialog boxes 
owned by Desk Accessories, _TEIdle handles blinking the caret 
in TextEdit records managed by the application. 

Also in the June issue, “Кат Warrior" asks questions con- 
cerning MPW and the Font Manager. The problem seemed to 
deal more directly with the Menu Manager, in particular the 
SetItemMark() routine. I ran into a problem with GetItemMark() 
that took some time to figure out, and resulted in symptoms 
similar to those described by Ram Warrior. According to IM, 
page 1-359, the calls to the two routines look like: 


Set I temMark( theMenu: MenuHand]e, i tem: INTEGER, markChar : CHAR); 
GetItemMark С theMenu:MenuHandle, 
item: INTEGER, VAR markChar : CHAR 2; 


This isn't quite the case. It is impossible to put a single byte 
onto the stack; markChar will be extended to a word before being 
pushed onto the stack. Since compilers do this automatically, 
you'll never notice this. On the other hand, if you declare 
markChar to beaone-byte variable, then pass a pointer to it, some 
compilers will do exactly that: allocate one byte of space on the 
local stack frame and pass a pointer to that byte. However, 
GetItemMark() actually expects to be handed a pointer to a word, 
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with markCharto be placed in the high (least significant) byte. So 
passing a pointer to a single byte, results in the item's mark 
information being stuffed into the next byte of memory, whatever 
that happens to be. The upshot is that you have to declare 
markChar to be a 2-byte quantity (INTEGER, for instance), and 
look for the item's mark information in the high byte, otherwise 
notonly do you not get the information you requested, you trash 
some innocent bystander, which most likely will cause you grief 
elsewhere. I don’t know if this has any bearing on Ram Warrior's 
problem, but others may find this bit of MacTrivia helpful. 

Finally, a problem of my own. I have a program, “Сга- 
phToolz," that allows the user to type in an equation for a 
function, which may then be graphed (among other things). To 
enter the function, the user is presented with a dialog box which 
contains an EditText item. In order to make as many people 
comfortable with the program as possible, I allow BASIC-style 
formulas to be entered, in particular exponentiation may be 
denoted by the *^' character. Thus someone may enter “x42+3”, 
meaning x squared plus three. This works just fine until we 
switch to another dialog box which displays the user's function 
ina StaticText item; it appears as “x+3”; the ^and the 2 disappear. 
This is cosmetic only, and the same thing may be entered in the 
Fortran style as “x**2+3” but it is sort of annoying. After not 
thinking about it for a while, I realized that the Dialog Manager 
saw the 42 as an invitation to do a little text substitution ala 
ParamText(). So, I did the obvious thing inserted the following 
lines just before opening the offending dialog box: 


ParemText С “\Р^@”, “\P°1%, “\P°2"%, "NP73^ ); 


I figured that I could trick the Dialog Manager into substitut- 
ing in exactly what it was replacing. But no, the ROMs are 
smarter than that and caused the Mac to hang. So I ended up 
adding the (mathematically equivalent) 


РагапТехі С "(Р%%0% "NAPxxj^, “\P**2%, “\P**3" ); 


which sort of solves the immediate problem. I am in the midst 
of writing a routine to support real TextEdit records in a dialog 
box via the userItem mechanism. 


Show Clipboard Function with 
Custom TextBox Routine 
by 
Tom Saxton 

In several situations it is desirable to avoid TextEdit when 
displaying text. As an application of the necessary technology, I 
have written a Show Clipboard function which displays text 
without any help from the TE routines. Basically the only trick is 
to write your own word-wrapping routine. 

Once this is done, you have a fairly compact little routine 
: which then opens itself to easy modification. So, for instance, you 
may want to do something smart with tabs. This would be much 
easier than rebuilding the TE routines (see Bradley Nedrud's, 
"Extending Text Edit for TABS" in the Nov. 1986 issue of 
MacTutor.) Of course, this is handy only for displaying text, you 
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lose the ability to edit the text. 

The following program is pretty simple. It builds the , File 
and Edit Menus, then opens a window in which the Clipboard is 
displayed. Any editing operations from the DAs which change 
the contents of the Clipboard will be noticed and the window 
updated. 

The word wrapping does the following. Beginning with the 
first character it is handed, it marches through the text character- 
by-character. It first checks for a carriage return. If it finds one, 
it prints the characters looked at so far and starts the process over, 
beginning with the next character. If the current character is not 
a carriage return, it adds the width of the current character to a 
running total. If that running total exceeds the width of the text 
rectangle, it backs up to the last word break and prints the line, 
then starts the process over. If the current character is not a CR 
and the accumulated length is not too long, then it decides if the 
current character is a break between words. If so, it stores the 
current position as a place to break. In this simple case, a 
character is a break between words if it is a space or a tab. 

This process is repeated line-by-line until the text is ex- 
hausted, or until the bottom of the text box is reached. In the event 
that a line runs off the right edge of the text Rect without ever 
encountering a word boundary, as much of the string as possible 
is printed (all but the last character of the current line), and the 
next line is started. 

Finally, since supporting the drawing of PICTS on the Clip- 
board adds all of about 10 lines to the code, I do that as well. The 
only trickery is to move the upper left corner of the picFrame to 
the upper left corner of hte display Rect. Alternatively, one could 
center the PICT in the display Rect, or scale it to fit in the display 
Rect. To center the PICT, do this: 


drewACenteredPicture С textWindow, dispRect, thePicture ) 


WindowPtr — textWindow; 
Rect *dispRect; 
1525” thePicture; 


Rect drawRect; 

short hMove, vMove; 

drawRect = (*thePicture)->picFrame; 

hMove = dispRect-) left - drawRect. left; 
hMove += dispRect— right - drawRect.right; 
hMove /= 2; 


vMove = dispRect-?top - drawRect. top; 
vMove += dispRect->»bottom - drawRect .bottom; 
vMove /= 2; 
OffsetRect С &drawRect, hMove, vMove ); 
DrawPicture С thePicture, &drawRect ); 

) /* drawACenteredPicture */ 


To scale it is even easier, no OffsetRectQ), just: 


DrewPicture С thePicture, &dispRect ); 


A scroll bar and some I/O and one could easily write a 
ScrapBook-like application. Add horizontal and vertical scroll 
bars and add a couple of paramters to the drawing routines and 
you have a scrolling ScrapBook. No doubt there are many 
other applications of these ideas. 
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* include <abc.h) 


include <MacTypes.h> 
*finclude <Quickdraw.h> ES ee сс: > 
"include «МіпдояМаг.һ» Е : Clipboard == 
include  «EventMgr .h» : a = = 

#їпс1иде <MenuMgr .h> 


"include «DeskMgr.lv of 
®include <ScrapMgr .h? 4: 
ы 
#деГ1пе AppleID 30 ak 
ttdef ine FileID 31 > 
"define | EditID 32 =f 
"J: 
MenuHandleappleMenu, : 
fileMenu, 

editMenu; Ш 


EventRecord theEvent; 
WindowPtr — clipWindow; 


short scrapCompare; 
char theStr ing[2561; 
Boolean (опе; 


Fig. 2 Our show clipboard function shows what a Mac Il 


riu does to cmd-shift-3 picts! 
initializeC); do ( 

) eee /* see if scrap has changed recently.. */ 

if CscrapCompere NEQ InfoScrap()->scrapCount) ( 
GetPort С &savePort ); 

initialized) SetPort С clipWindow 9; 
R InvalRect С &clipWindow- portRect 2; 
er UMEN SetPort С savePort ); 
InitGraf(&thePort); scrapCompare = InfoScrap()->scrapCount; 
InitFontsO; ) 
ee? if (GetNextEvent С everyEvent, &theEvent )) ( 
Ет” switch С theEvent.what ) ( 

) | case mouseDown: 

eee thePert = FindWindow С theEvent.where, 
FlushEvents ( everyEvent, 0 ); 127 Қаның › { 
setUpMenust?, case inContent: 
SetRect С &wRect, 60, 50, 450, 250 ); if € FrontWindow() МЕО wWindow ) 
clipWindow = NewWindowC NULL, &wRect, *MPClipboard^, TRUE, SelectWindow ( wWindow ): 

0, -1L, FALSE, NULL D; ’ 

, / ; ; break; 


/* force an initial update of Clipboard window */ 


scrapCompare = InfoScrap()->scrapCount + 1; case inMenuBer : 


М doMenuClick(); 
done = FALSE; break; 
ЖЕСТ case inSysWindow: 
) /* initialize */ SustemClick С &theEvent, wWindow ); 
break; 
n tUpMenus C) default: 
eppleMenu = NewHenu С AppleID, “\Р\й24” ); Cara RC 
AddResMenu С appleMenu, ‘DRVR’); ) /* switch thePart */ 
InsertMenu ( appleMenu, 0 ); break : 
fileMenu = NewMenu C FileID, “\PFile” ); ace keyDown: 
AppendMenu С fileMenu, “\PQuit’ ); done = TRUE: 
InsertMenu С fileMenu, 0 ); break: | 
editMenu = NewMenu С EditID, “\PEdit” ); 4 


case updateEvt: 
if € CWindowPtr) theEvent.message EQ 
clipWindow ) 
updateClipWindow € clipWindow ); 
break; 
) /* setUpMenus */ cese activateEvt: 
if С CWindowPtr) theEvent.message EQ 
doEventsC) clipWindow ) ( is 
SetPort С theEvent.message ); 
if CtheEvent modif iers bAND activeF lag) 
DisableItem С editMenu, 0 ); 
else 
EnebleItem С editMenu, 9 ); 


AppendMenu С editMenu, “\PUndo;(-;Cut;Copy;Paste; Clear” ); 
InsertMenu С editMenu, 0 ); 
DrewMenuBar(); 


WindowPtrwWindow; 
GrafPtr sevePort; 
INTEGER thePart; 


done = FALSE; 
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) 


break; myTextBox (textWindow, textRect, textPtr, textLength) 
) /* switch theEvent.what */ WindowPtr — textWindow; 
) /* if GNE */ Rect *textRect ; 
) while С NOT done 2; register cher  textPtr(]; 
) /* doEvents */ pg textLength; 
doMenuClickC) register long index; 
long menuChoice; FontInfo theFont Info; 
short textHeight, 
menuChoice = MenuSelect С theEvent.where ); boxWidth, boxHeight, 
doMenuChoice С menuChoice 2; theHeight, strLength; 
long stertLine, canBreak; 


) /* doMenuClick */ 
TextFont (3 ); /* Geneva */ 


doMenuChoiceC theMenu, theItem ) TextSize (С 12); /* 12 point */ 
АА theMenu, theltem; TextFace ( Ø ); /* Plain Text */ 
short accNumber; GetFontInfo С &theFontInfo 2; 
textHeight = theFontInfo.ascent + 
switch С theMenu 2 ( theFont Info .descent*theFontInfo. leading; 
case AppleID: 
GetItem С appleMenu, theItem, theString ); boxWidth = textRect— right - textRect-? left; 
accNumber = OpenDeskAcc С theString 2; boxHeight = textRect— bottom - textRect-? top; 
break; 
case FileID: theHeight = textRect- top - theFontInfo.descent; 
if С theItem EQ 1 ) strLength = 0; 
done = TRUE; startLine = cenBreek = -1; 
break ; 
case EditID: for С index = Ø; index < textLength AND theHeight < 
if С NOT SystemEdit С theItem - 1) ) boxHeight; index** ) ( 
SysBeep С 2 ); if С textPtr[index] EQ CR ) /* if cher CR */ ( 
break; theHeight += textHeight; 
default: MoveTo С textRect-> left, theHeight ); 
break; DrawText € textPtr, startLinet1, 
) /* switch */ index-startLine-1 ); 
strLength = 0; 
HiliteMenu С Ø ); stertLine = canBreak = index; 
) else /* check for word wrap */ ( 
) /* doMenuChoice */ strLength += CharwWidth С textPtr[index] ); 
if € strLength > boxWidth ) ( 
updateClipWindow ( badWindow ) if С canBreak > stertLine ) 
WindowPtr badWindow; index = canBreak; 
else 
GrafPtr savePort; index-; 
Rect dispRect; theHeight += textHeight; 
Handle theHandle; MoveTo С textRect-> left, theHeight ); 
long offset, DrewText С textPtr, startLinet1, index-startLine-1 ); 
theSize; strLength = 9; 
stertLine = canBreak = index; 
theHandle = NewHandle С 8L ); ) else if € textPtr[index] EQ ° * OR 
textPtr[index] EQ TAB ) 
GetPort С &savePort ); canBreak = index; 
SetPort ( badWindow ); ) 
BeginUpdate С badWindow ); ) /* for index loop */ 
EreseRect С &badWindow->»portRect 2; theHeight += textHeight; 
dispRect = badWindow- portRect; MoveTo С textRect-> left, theHeight 2; 
InsetRect € &dispRect, 5, 5 ); DrewText С textPtr, (short) (startLine* 1), 
if € CtheSize = GetScrep С theHandle, (short) Cindex-startLine-1) ); 
‘TEXT’, &offset 22» 0 ) ( ) /* myTextBox */ 
HLock С theHandle ); drawAPicture С textWindow, dispRect, thePicture ) 
myTextBox ( badWindow, &dispRect, WindowPtr . textWindow; 
*theHandle, theSize ); Rect *dispRect; 
HUnlock С theHandle 2; PicHendle — thePicture; 
) else if С CtheSize = GetScrep (С theHandle, ( 
‘PICT’, &offset )) › 0 ) { Rect  drewRect; 
drawAPicture ( badWindow, &dispRect, drewRect = (*thePicture)->picFrame; 
theHandle ); OffsetRect С &drawRect, - drawRect.left + 
) dispRect- left, - drawRect.top + dispRect-?top ); 
EndUpdate С bedWindow 2; DrewPicture С thePicture, &drawRect ); 
DisposHandle С theHandle 2; ) /* drewAPicture */ 


) /* updateClipWindow */ 


© The Essential MacTutor, Vol. 3 143 


Technical Note 
ShiftMod Patch 


Last week we were talking with an IBM freak about the 
differences between our Macs and his footrest, that is, PC. One 
of his complaints about the Mac was that you get upper case 
letters when both the shift key and caps lock key are down at the 
same time. He wanted to be able to type a lower case letter if the 
caps lock key was down by pressing the shift key. Then he could 
type sentences like “i WISH i HAD A mACINTOSH" without 
havingtohold down the shiftkey the whole time. Well, Mac fans, 
fear not. Now the Mac can do this too. Say hello to Mr. ShiftMod. 

All that is really needed is a tail patch to. GetNextEvent that 
checks if a keyDown or autoKey event occured while the caps 
lock and shift keys were held down. The only problem with 
implementing it is that because  GetNextEvent is a stack based 
trap (it gets its parameters from the stack) the patch requires a bit 
of self modifying code to get it to set things up correctly. While 
this example is trivial, the technique used here can be used to 
patch any stack based trap routine. 

A tail patch is something that first calls the original trap and 
then does some post-processing before returning to the caller. If 
the original trap is not stack based, we can do aJSR OriginalTrap 
at the beginning of our patch, do our post-processing, and end 
with an RTS. However, if the original trap is stack based it will 
expect the stack to look a certain way when it gets called. By 
doing a JSR to it, we put a return address on top of the existing 
stack which, in effect, shifts all of the parameters by 4 bytes 
(relative to the top of the stack). The routine being called does not 
know about the extra return address and will use the wrong bytes 
as parameters. 

The code listed here is an application, but itcan be easily (via 
ResEdit) be made into an INIT resource and pasted into your 
system file. It installs itself in the system heap and hangs around 
as long as you don't turn your Mac off. This code is useful if you 
want to install any event processing stuff that is global for all 
applications. For instance, you could call Eject every time you 
detect a diskEvt and count how many times someone tries to 
insert a disk in a minute. Or you could do something semi-useful 
like adding a keyclick after keyDowns (how about a mouseclick 
on mouseDowns?) for debugging. 

Now how about an IBM hacker writing a routine to make 
his machine return upper case letters when both the shift key and 
caps lock key are down? Is it even possible? 


/* shif tMod.c 2 July 1987 
x 


* by Mike Scanlin and Andy Voelker 
x 


* This program installs a tail patch on -GetNextEvent so 
* that the shift key toggles between upper and lower case 
* letters if the caps lock key is down. 
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x 


* No toggle is done if the option and/or command key wes 
* held down. 


*/ 


*include *Asm.h^ 
*$include "EventMgr .h^ 


"define what OFFSETCEventRecord, what) 
8define message OFFSETCEventRecord, message ) 
“define modifiers OFFSETCEventRecord, modifiers) 
“define GetNextEvent £xA970 
"define JMP 0х4ЕҒ9 
"define memFullErr - 108 
main() 
( 

asm ( 


move.1 03,-С9Р) 

/* set up the UMP instruction at the end of the patch */ 
lea @patchExit, Аб 
move *JMP , CAD) 


/* get the old trap address */ 
move ®GetNextEvent, 00 
-GetTrepAddress 


/* set up the JMP instruction that calls the original trap */ 
lea eorigIrap, A1 
nove *JMP СА1)+ 
томе. 1 А0,(А1) 


/* get some space іп the system heap */ 


lea @last, Ad 

lea ef irst,A1 

suba.] А1,А0 

move.| А0,00 

move.| 00,03 /* save for .BlockMove */ 
-NewPtr SYS 

cmpi "memFullErr,D9 

beq.s @noPatch 

move.| А0,-(ӨР) /* save for _BlockMove */ 


/* set the trap address to the space we just got in the 
* system heap 
*/ 

nove "GetNextEvent, 00 

_SetTrapAddress 


/* now move it into place */ 
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lea ef irst,AQ move what(Ad), DØ 


томе. (SP)+,Al стрі *keyDown, DØ 
move.) 03,00 beq.s @isKeyDown 
-BlockMove стрі SeutoKey, DO 


bne.s epetchExit 
@noPatch томе. Л (SP)+,D3 


rts 6isKeyDown move modif iersCA2)2,D0 
endi "shif tKey*alphaLock*opt ionKey 
/* Here's the new _GetNextEvent. It calls the existing +cmdKey , DØ 
* _GetNextEvent and then checks if a keyDown or autoKey eor i 8shif tKeyt+a lphaLock , 00 
* event is being reported. bne.s epatchExit 
x/ 
томе. 1  message(A0)2,D0 
/* Ѕауе original return eddress */ cmpi.b ЯА”/00 
ef irst lea @exi tAddress, Ad bmi.s @patchExit 
move.1 (СР )+, CAG) стрі.Ь %/Z’ 00 
bgt.s @patchExit 
/* save ptr to event record */ eddi.b %’a’-’A’, DO 
lea беуеліРіг,А0 move.1 D®,messageCAd) 
move.] СР), САЙ) 
/* return to original caller via long JMP */ 
/* return to our routine */ @patchExit пор 
pea @tailPatch @exitAddress nop 
nop 
eor ідТгарпор /* JMP to original trap */ 
nop 
nop eeventPtrdc.10  /* storage for event record ptr */ 
6tailPatch lea GeventPtr Ad @last 
move.] (CAG), AQ } 
) 


/* Is it а keyDown or autoKey? */ 
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C Workshop 


Using Regions in Medicine with C 


Fun with Regions: Part I, High Level Language 
Implementation 

As one looks through a tattered and tear-stained copy of 
Inside Macintosh , there is little that would be considered colorful 
or dramatic language. The following statement, from the section 
on Quickdraw, stands out: “Quickdraw has the unique and 
amazing ability to gather an arbitrary set of spatially coherent 
points into a structure called a region, and perform complex yet 
rapid manipulations and calculations on such structures. This 
remarkable feature not only will make your standard programs 
simpler and faster, but will let you perform operations that would 
otherwise be nearly impossible; ..." 

One of the authors read this at the very time that he wanted to 
do something nearly impossible. The job at hand was a medical 
instructional program, “Burnsheet”, in which the outline of a 
thermal injury is drawn on a standard silhouette of the body (fig 
1.). Since many formulas for treating burn patients depend on 
knowing the area affected, it was desirable to calculate the area 
of the burn(s) as well. Thus the specific programming tasks were 
to be able to draw arbitrarily shaped regions on the screen and to 
find the area of these areas. This first article will show an 
approach to these tasks using high-level (C and Pascal) program- 
ming. The complete code for a C language program is at the end 
of the article; and the important routines, as implemented in 
Pascal, are interpolated into the text. In many cases program- 
ming elegance has been sacrificed for the sake of clarity; espe- 
cially when an elegant approach could not be found. Part II will 
present an evolutionary approach to the assembly language 
optimization for speed in the computation of arbitrary areas on 
the Macintosh. 

In addition to Inside Macintosh, some germinal information 
on region drawing 15 found in “Quickdraw Does Regions" 
(Derossi, C., MacTutor 1, February 1985 pp 9-17). He outlines 
the basic steps as follows: (a) Initialize a variable ( a 
regionhandle) with a call to NewRegn. (b) Call OpenRgn to start 
a new region. (c) Do whatever drawing you want. (d) Call 
CloseRgn to stop the region definition. In a more recent article 
(Gordon, B.: Polygons and Regions as Quickdraw Objects. 
MacTutor May 1987, pp 41-53), further insight is given into the 
way regions are encoded - especially the mysterious optional 
region drawing information which is present when a region is not 
rectangular. 

The matter of finding the area of irregular regions is quite a 
common task in geography, chemistry (chromatograph spots, for 
example), and many aspects of biology. Methods for accom- 
plishing the task range from analytic solutions where the 
boundaries are defined by well-behaved mathematical functions 
to such brutal kluges as weighing paper on which the region has 
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Figure 1. Outlining the Burned Region 


Use of regions in medical research 


been traced. An elegant general approach for finding the area of 
a large class of irregularly shaped regions divides the region into 
triangles and trapezoids (Stolk, R., and Ettershank, G.: Calculat- 
ing the Area of an Irregular Shape. Byte, February 1987, pp 135- 
136.) This method requires, however, that the vertices of the 
perimeter be described explicitly as cartesian coordinates - not 
the Macintosh definition. It will not work for regions that are 
disjoint or have holes in them. 

Region Drawing Routines: Although several published pro- 
grams have shown how tocreate regions оп the screen by passing 
explicit parameters to drawing commands; such as 

FrameRect(myRect, 10,20,30,40), etc., 

what I wanted was to draw an arbitrarily shaped region on the 
fly under mouse control - something like the lassoo in many Mac 
graphics programs. My answer to this need is the DoRegion 
procedure. It is well to initialize the global regionhandle 
TotalRgn early in the program. In the C program shown this is 
done just before the main event loop in order to avoid a bomb if 
the area computation is requested before the region is actually 
drawn. 

A Pascal implementation of the procedure is as follows: 


var 
TotalRegion RgnHandle; 
procedure DoRegion; 
var 
pl : Point; 
p2 : Point; 
OldTick : Longint; 
begin 
TotalRegion := NewRgn; 
OldTick := TickCount; 
Repeat 
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GetMouse(p 1); 

MoveTo(p1.h,p1.v2; 

p2 := pl; 

Until Button = True; 

OpenRgn; 

ShowPen; 

PenMode(patXor); 

Repeat 
Ge tMouse(p2); 
Repeat Until COldTick © TickCount); 
LineTo(p2.h,p2.v); 

Until Button © True; 

Repeat Until COldTick € TickCount); 

LineToCp1.h,p1.v2; 

PenNormal; 

HidePen; 

CloseRgn(TotalRegion); 

Inver tRgn(TotalRegion); 

end; 

The mouse position is tracked until the button is pressed. 
While the button is down, a sequence of lines is drawn following 
the movement of the mouse. In order to make the drawing less 
jumpy, it is synchronized with the vertical retrace period by 
waiting until the “tickcount” changes before updating the draw- 
ing process (Knaster, S.: “How to Write Macintosh Software”, 
Hayden, Hasbrouck Heights, NJ, 1986, pp 334-336). The calls 
to ShowPen and HidePen are necessary to balance opposing calls 
made by OpenRgn and CloseRgn. 

An analogous procedure for drawing a rectangle under mouse 
control is shown below: 


var 
TotalRegion RgnHendle; 
procedure DoBox; 


pl : Point; 

p2 : Point; 

p3 : Point; 

OldTick : Longint; 

MyRect Rect; 

begin 

TotalRegion := NewRgn; 

OldTick := TickCount; 

PenPat(gray); 

PenMode(patXor ); 

Repeat 

Ge tMouse(p 1); 

p2 := pl, 

Until Button = True; 

OpenRgn; 

ShowPen; 

PenMode(patXor ); 

Repeat 

Pt2RectCp1,p2, MyRect); 

Repeat Until COldTick © TickCount); 

FreneRectCMyRect); 

Repeat 
GetMouse(p3); 
Until EqualPt(p2,p3) © True; 


Repeat Until COldTick € TickCount); 
FremeRect CMyRect); 


p2 := p3; 
Until Button © True; 
Pennormal ; 
HidePen; 
PenPat(b lack); 
FrameRect(MyRect); 
CloseRgn(TotalRegion); 
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Inver tRgn(TotalRegion); 
end; 

After the mouse button is pushed, a “preview” rectangle is 
drawn in gray as the mouse position is changed. When the button 
is released, the rectangle is “enforced” as the final choice. 
Although these procedures invert the pixels in the region finally 
chosen, various types of painting or filling could also be done and 
the last FrameRect in DoBox could be changed to FrameOval, 
etc. 

Area Computation: The region record contains the coordi- 
nates of the smallest rectangle which will enclose the region, the 
rgnBBox. Asa firstapproach to determining the region area, one 
might "take a poll" of every pixel within this box to see whether 
it is actually in the region. The toolbox function PtInRgn, when 
passed a point and a handle to a region, returns the Boolean value 
true if the point actually resides within the region. The number 
of true points enumerated in this way should be proportional to 
the area of the region with a degree of precision at least as good 
as the ability to draw on the screen with the mouse. 


function CountPixCtheRegion : RgnHandle): LongInt 
var 


pt : Point; 
rgn : Region; 
temp :  LonglInt; 
begin 
temp := 0; 
гоп :* theRegion^^; 
for pt.h := rgn.rgnBBox. left to rgn.rgnBBox.right do 
begin 
for pt.v := rgn.rgnBBox.top to rgn.rgnBBox.bottom do 


if PtInRgn( pt, TheRegion) then temp := temp + 1; 
nee :* temp; 
end; 

The C and Pascal Countpix routines work nicely for rela- 
tively small regions. For those drawn in the Burnsheet program, 
processing time ranged from three to thirty ticks (6oths. of a 
second). It is possible, however, to draw really large and bizarre 
regions with many holes that can take ten minutes to compute. 
Although finding the area of such regions by conventional means 
"would otherwise be nearly impossible," this is hardly a satisfac- 
tory performance; and clearly some form of optimization is 
indicated. An important step towards fashioning and debugging 
a faster routine for estimating the area of an arbitrary region is a 
method for visualizing the region information as it exists in 
RAM. Although this can be done using a debugger, it is more 
convenient to have this as part of our region program. The C 
version of the "data" function reflects that language's general 
laissez faire attitude concerning mixing of pointer types in the 
blockmove step. Because of the ease with which the type of 
numerical representation (hex or decimal) can be specified 
within the printf routine, the C version first prints the hex version 
- as it would be seen with a debugger. After a mouse click, the 
decimal version is printed to the screen. Pascal seems to be more 
finicky about mixing different pointer types, so explicit type 
conversions are done. The Pascal version displays only the 
decimal representation of the data. In both versions only the first 
400 words of data are shown since this fits conveniently on the 
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screen. Displaying the hex numbers in Pascal and adding 
scrollers to display more data are - in the words of my old calculus 
book - left as an exercise for the reader. 

( This routine prints the first 400 words of а region record 

to the screen. It assumes that a regionhandle called total- 
Region has been declared and allocated ) 


procedure Date; 


var 
rgn Region; 
rgnpntr Ptr; 
size Integer; 
halfsize Integer; 
thebuf BUF ; 
bfpntr Ptr; 
myS tring 5іг255; 
1 : Integer; 
X : Integer; 
y : Integer; 

begin 

Wipe; 
TextSize(9); 
Tex tFont (Monaco); 
гоп :: totalRegion**; 


rgnpntr := ptr(totalRegion*); 

size := rgn.rgnSize; 

if size › 800 then size:= 800; 

bfpntr := ptrCéthebuf); 

BlockMove(rgnpntr ,bfpntr, size); 

MoveTot 10, 10); 

DrawString( ‘Here are the first 400 words of the region 
data. (FLAG = 327672”); 


x := 10, 

у := 20, 

for i := 1 to (size div 2) do 
begin 
MoveTo(x,y2; 


NumToStr ingCtheBuf (11, myStr ing); 

1f theBuf (i) < 32766 then 
begin 
1f theBuf ti] «10. then DrawString(’ '5; 
1f theBuf 1] «190 then DrewStringC' ”); 
1f theBuf (iJ «1000 then OrewStringC' '2; 
1f theBuf (i) «10000 then DrewString(' ‘); 
DrawString(MyString); 


end; 
1f theBuf [i] > 32766 then DrawString(’ FLAG’); 
x := x + 30; 
if Ci mod 16) = 0 then 
begin 
x := 10; 
y := y*1£; 
end; 
end; 


end; 

Figure 2 shows a “FatBits” view of a circle along with the 
function used to draw it and acquire a handle to the region it 
encloses. Figure 3 shows the data for this region as displayed by 
our data routine. Using this information youcan trace the way the 
region is encoded as as outlined in Bob Gordon's article (vide 
supra ). The first word (196) is the number of bytes of data in 
the record. The next four words are the coordinates of the region 
bounding box in “upper, left, bottom, right" form. The rest of the 
data consists of sequences as follows: Y,X,, X,, ...X,, FLAG. The 
flag word is 32767 (7FFF hex). Atthe very end of the record, the 
flag word appears twice. In each sequence the first integer word 
is a Y coordinate and the others up to the flag are X coordinates. 
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One may visualize the process of outlining theregion by thinking 
of moving a "pen" to the Y coordinate and toggling it on and off 
with each succeeding X value. For the circle shown (starting with 
the fifth word of data), the first Y position is 175 and the first X 
coordinate is 179. Turn the pen on at this point and draw 
rightward to the second X coordinate (186). Turn off the pen. 
Similarly expanding the next sequence: move to ( Y = 176, X = 
177); pendown; moveto (X = 179); penup; moveto(x = 186) - Y 
remains the same; pendown; moveto(x = 188); репор. Note that 
treating the data in this manner will draw all of the horizontal 
lines needed to frame the region. 

This representation of data is particularly efficient for dealing 
with regions with “square corners" - the sort that occur when 
windows overlap, etc. Even for more complex objects, the 
amount of data to be stored is much less required by more 
intuitive methods such as simply listing all of the points in the 
region or the vertices of its boundaries. 

Figure 4. shows a screendump of a really horrible region 
along with the times needed to estimate its area using the high 
level code presented here and with various levels of optimization. 
Using the high level routine, it required about seven and a half 
minutes to compute its area. By way of comparison, the small 
regions shown in the “Burnsheet” illustration (Figure 1.) took 
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Figure 2. "FatBits" View of a Circle 
less than a second using the same code. For complex regions 
such as this, the assembly language optimization improves the 
speed of computation by a very welcome factor of more than 
1000. 

Stephen Dubin, V.M D., Ph.D., Thomas W. Moore, Ph.D., 
and Sheel Kishore, M.S. may be reached at the Biomedical 
Engineering and Science Institute, Drexel University, 32nd. & 
Chestnut Sts, Philadelphia PA 19104. Phone: (215)-895- 
2219. CIS: 76074,55 ; Genie: S.DUBINp; Delphi: ESROG. 
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written by Stephen Dubin and Sheel Kishore copyrignt 1987 for 
MacTutor 

Latest revision 8/9/87 

Prepared with Megamax C System V3.0d. Users of other C systems 
should check for such things as size and manner of passing 
variables particularly point variables. Also check include 
files. */ 


8include <qd.h> 
"include <win.h 
include «dialog.» 
*include <menu.h> 
*include <event.h> 
8include <qdvars.h> 
* include <stdio.h> 


"define lestmenu 1/* number of menus*/ 
8def ine optionmenu 1 


é File Options 


Here is the first 400 words of region data in deciaal notation: 

0196 0175 0170 0200 0195 0175 0179 0186 FLAG 0176 0177 0179 0186 0188 FLAG 0177 
0175 0177 0188 0190 FLAG 0178 0174 0175 0190 0191 FLAG 0179 0173 0174 0191 0192 
FLAG 0160 0172 0173 0192 0193 FLAG 0182 0171 0172 0193 0194 FLAG 0184 0170 0171 
0194 0195 FLAG 0191 0170 0171 0194 0195 FLAG 0193 0171 0172 0193 0194 FLAG 0195 
0172 0173 0192 0193 FLAG 0196 0173 0174 0191 0192 FLAG 0197 0174 0175 0190 0191 
FLAG 0198 0175 017? 0188 0190 FLAG 0199 0177 0179 0186 0189 FLAG 0200 0170 0106 


Figure 3. Region Data for the Circle of Figure 2. 


Area output of our sample 


"define NULL ØL 
/* globals used by shell */ 


menuhandle mymenus(lastmenu* 1]; 
rect screenrect, prect; 

boolean doneflag, temp; 
eventrecord myevent; 

int code, refnum; 

windowrecord wrecord; 

windowptr mywindow, whichwindow; 
int themenu, theitem; 


/* globals used by region */ 
rgnhandle totalrgn; 

extern long tickcount(); 
long numpix,numtix; 


areal) 


long firstick, lastick; 
char firststring(255], secondstring[{255], printstring{255]; 
numpix = 9; 
firstick = tickcount(); 
countpixCtotalrgn); 
numtix = tickcount() - firstick; 
moveto( 10,20), drawstring(“Using all C code”); 
strcepy(firststring, ^");strcpyCprintstring, **); 
numtostring(numpix, f irststr ing); 
strcat(printstring, "Number of Pixels = *); 
Strcat(printstring, firststring);strcpy(firststring, ^"); 
moveto( 10,30); drawstring(pr intstr ing); 
strcpy(pr intstr ing, ^^); 
numtostring(Cnumt ix, f irststr ing); 
Strcet(printstring, "Number of Ticks = “); 
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é File Options 


| Using al! С code 
| Number of Pixels = 26502 
| Number of Ticks = 27031 


| Using С code and bypass trop dij 
| Number of Pixels s 26502 
| Mumber of Ticks = 26901 


| Asseably setup then jsr to RON 
Number of Pixels = 26502 
1 Nuaber of Ticks = 26707 


| All assesbi 
4 Number of Pixels = 26502 
7 Number of Ticks = 15 


| Trap address = 40COD4 


Figure 4. Area of a "Difficult" Region Using High-Level Code end 
Various Levels of Assembly Language Optimization 


An outragious region! 


streat(printstring, firststring); strcpy(firststring, "^2; 
moveto( 10,40); drawstring(printstring); 
ыд OL 


countpixCtheregion) 
pee theregion; 


point pt; 
region rgn; 

rgn = **theregion; 

for(pt.a.h=rgn.rgnbbox.a.left; pt.a.h «s 
rgn.rgnbbox.a.right; pt.a.h**) 

for(pt.a.v=rgn.rgnbbox.a.top; pt.a.v <= 
rgn.rgnbbox.a.bottom; pt.a.v*t*) 
if Cptinrgn(&pt, theregion)) 
питріх++; 


) 
dataC) 
( 


region rgn; 
int = size,i; 
int nyerrey [400]; 
wipeC2; 
гоп = **totalrgn; 
size = rgn.rgnsize; 
size = ( (size › 800) ? 800: size); 
blockmove(*totelrgn, &myarray, Clong)size); 
moveto( 10, 10); 
printfC^Here is the first 400 words of region data in 
hexadecimal notation: \n”); 
for(iz0; i<Csize/2); ++i) ( 
printfC^ 304x”, туаггауГ1 1); 
ызы ргіп (40%); 


printf(^ Press the mouse button to continue. ^); 
ff lush(stdout); 
while C!button()); 
міреС); 
moveto( 10, 10); 
printf(^Here is the first 400 words of region data in 
decimal notation: in^); 
for(i-0; i<Csize/2); ++i) ( 
if Cmyarrayli 1232766) printf(^ FLAG’); 
else printfC* 204d’, myarrayli)); 
ifCICCi 1261622 printfC*\n”); 


fflush(stdout); 


ak /* draws freehand region */ 


point pl,p2; 
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long oldtick; 
wipe(); 
totalrgn = newrgn(); 
whileC!button()){ 
ge tmouse (&p 1); 
movetoCp1.8.h,p1.8.v2; 
ре. 


openrgn(); 

showpen(); 

penmode(patxor ); 

whileCbutton¢ )) ( 
getnouse(&p2); 
whileColdtick == tickcount()); 
linetoCp2.8.h,p2.8.v2; 


whileColdtick == tickcount()); — /* to avoid flickering */ 
linetoCp1.8.h,p1.8.v); 

pensize(1, 1); 

pennormal(); 

hidepen(); 

closergn( totairgn); 

invertrgnCtotalrgn); 


) 


dobox() /* draws rectangular region*/ 
point pl,p2,p3; 
boolean equalptd); 
long oldtick; 
rect  myrect; 
wipeC2; 
oldtick = tickcount(); 
totalrgn = newrgn(); 
penpat(gray); 
penmode(patxor ); 
while( !button()){ 
ge tmouse (&p 1); 
Ade 


openrgn(); 

showpen(); 

penmode(patxor ); 

whileCbutton( )){ 
pt2rect(&p1,&p2, &myrect ); 


whileColdtick == tickcount());/* to avoid flickering */ 


framerect(&myrect); 
while Cequalpt(&p2,&p3)&& buttonC)) getmouse(&p3); 
whileColdtick == tickcount()); 
framerect(&myrect); 
р2-р3; 


pensize(1, 1); 
pennormal(); 
hidepen(); 

penpat (black); 
penmode(patcopy); 
framerect(&myrect); 
closergnCtotalrgn?; 
invertrgnCtotalrgn); 
pennormal(); 


) 
wipeC) 
( 

rect г; 
setrect(&r,0,9,510, 300); 
eraserect(&r ); 
pennormal(); 


QUEEN 


int i; 
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initnenusC); 

mymenus[1) = newmenuCopt ionmenu, *Options^); 

eppendmenu(mymenus[ 1], “Draw Freehand;Draw Box;Compute 
Area;Region Data; Quit”); 

for Ci=1; i<=lastmenu; i++) insertmenuCmymenusli), 0); 

drawmenubar ); 


docommand( themenu, thei tem) 
int themenu, theitem; 


int i; 

switch Cthenenu) ( 

cease optionmenu: 

switch( thei tem) ( 

case 1: doregion(); break; 
case 2: dobox(); break; 
cese 3: area(); break; 
case 4: data(); break; 
aad 5: doneflag = 1; break; 


Ae 
hilitemenuC0); 


nainC) 


rect windowrect; 
initgraf C&theport2; 
initfontsC); 
f lusheventsCeveryevent, 2); 
initwindows(); 
setupmenus(); 
initdialogsCNULL); 
initcursor(); 
setrect(&screenrect, 2, 48, 518, 338); 
doneflag = 0; 
mywindow =newwindow(&wrecord,&screenrect, “Region Fun”, 1,0, 
Clong)-1, 0, Clong)20); 
setpor t(mywindow); | 
blockmoveC&theport-?portrect, іргесі, Clong)sizeof prect); 
insetrect(&prect, 4, 0); 
textfont(4); 
textsize(9); 
textmode(2 ); 
ara = newrgn(); /* avoid bomb if compute is first */ 
do 
systemtask(); 
temp = getnexteventCeveryevent, &myevent); 
switch (myevent.what) ( 
case mousedown: 
code = f indwindow(&myevent where, &whichwindow); 
switch (code) ( 
case inmenuber : 
docommand(menuse lect(&myevent.where)); break; 
case insyswindow: 
systemclick(&myevent, whichwindow); break; 
case incontent: 
if Cwhichwindow != frontwindow()) 
selectwindow(whichwindow); 
else globaltolocal(&myevent .where); 
break; 


break; 

case updateevt: 
se tpor t(mywindow); 
beg inupdate(mywindow 2; 
wipe(); 
endupdate (mywindow); 
break; 


) 
) while Cdoneflag == 9); 
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Advanced Mac'ing 


Rom Reference DA for Inside Mac in C 


Wearing out yer copy of IM? 

After you've been programming the Mac for a while, you find 
that you're starting to wear out your copy of Inside Macintosh, 
It's not that you're looking up the hundreds of calls in order to 
figure out what they do, it's just that no human being can 
remember that many parameter sequences. With the storage 
capacity available nowadays, this is rather silly - we should be 
letting the Mac do the lookup for us - and that is exactly the 
purpose of the ROMRef DA. 

This desk acccessory is NOT a help facility (altho one could 
be built from it rather easily) but only a compilation of the format 
for every callin volumes 1-3 of IM. The advantage is that looking 
up acall places a copy of the call, with all parameters, directly on 
the clipboard, where it can be simply pasted into the program. 

I used the Clock DA by Don Melton as a skeleton for 
ROMRef, and it proved mighty helpful; thanks oodles, Don!! 
Two versions are included: one operates in ‘C’ format, while the 
other is in Pascal format. The ‘C’ version is set up to put the calls 
іп the format used by Consulair C (4.53 was used to develop this), 
while the Pascal version is non-specific (I don’t work in Pascal). 

Operation: is quite simple. The data file should be in the 
“blessed folder” or with the editor. When the DA is invoked, it 
puts a menu up. Select “Lookup” and a selection box appears 
listing all of the toolbox managers in alphabetical order: 


Fig. 1 Our own RomRef Data Base Manager! 


select 8 ROM Manager 


ШАБ 


Once you have selected a manager, a second window is 
displayed with all of the calls for that manager again listed in 
alphabetical order: 

Whena callis selected, any of the 1st four buttons on the right 
will place the call on the clipboard. Either of the accept buttons 
will cause the call to replace the former contents; either of the 
append buttons will cause the call to be appended to the previous 
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Copy в sample call to the clipboard Accept 


АТЕАЧЈЕ =p 
ATPCloseSocket 
ATPGetRequest 
ATPLoad 
ATPOpenSocket 
ATPReqCancel 
ATPRequest 


Rccept/Continue 


Rppend 


Rppend/Continue 


Fig. 2 Getting the rom call on the clipboard 


contents. The "continue" option allows you to return to the 
manager selection window for another call. 

Two entries on the menu affect how the call will be formatted 
on the clipboard. “Show Memory Mashers" causes a comment to 
be placed before the call if the call selected can possibly cause 
memory to be re-arranged. “Disable Typecasting" is available 
because the default is to have every variable in a call shown with 
its type; you may not always want this. 

Internals: This DA does NOT use the list manager, since I 
wanted it to work with 64K ROM machines. It turned out to be 
very illuminating about how to work with (and around) the dialog 
manager. 

One advantage of the approach taken by Don's DA is in the 
simplicity of debugging. The locking of the DA when a menu 
routine is invoked allowed me to debug exactly as if it were a 
normal application, with the code locked in the heap. Having 
function names embedded by the compiler allowed TMON (best 
thing since peanut butter on hot toast!) to work to its fullest and 
kept me from going absolutely berserk in the early stages. I found 
that the scrolling selection window was the most complex part of 
the program to debug. I used the DA Sampler for testing. 

| | ithi ; are almost identi- 
cal to those in a normal application except for one subtlety that 
drove me crazy for several days... 

Macintosh Revealed mentions a bit in the event record that is 
used to indicate to an application if a DA window has just closed. 
According to Apple, applications should not depend on this - but 
MacWrite does! (it crashed with the famed ID=02 bomb every 
time I closed a ROMRef window..) Therefore, I have to set the 
windowType field of the dialog box window record to “dia- 
logKind" when starting processing (so the Dialog Manager will 
recognize it) and reset it to a DA window just before closing the 
window (so application programs won't croak in surprize). With 
the windowType fields properly set, ROMRef now works with 
all of the editors I have tried it with, including MacWrite and 
MacAuthor. (For unknown reasons I honestly haven't pursued, 
Word doesn't crash, but ROMRef doesn't affect its clipboard 
after the first lookup. If you do all your program editing in Word 
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and track this down, please let me know what's wrong) 

Scrollbars within the Dialog Manger; The scrolling selection 
window is composed of two user items: the text box and the 
scrollbar box. The scrollbar is declared to RMaker as a user 
item and actually created in the application with NewCon- 
trol. Using a scrollbar within the dialog manager turns out to be 
a truly awesome pain-in-the-touche, whereas simply using the 
dialog manager to detect a click in the scrollbar rectangle be- 
comes very easy to deal with. 

When a click is detected within the scrollbar box, we simply 
use GetMouse( to retrieve the current position of the mouse, and 
use the standard control manager functions. The list being 
displayed is a text edit record (CRs end lines) and so the amount 
to scroll is a simple function of number-of-lines-scrolled times 
the lineheight. 

One matter that added a little complexity to scrolling was 
dealing with trying to scroll beyond the limits of the list. The 
scrollbar maximum is set so that the bottom line of the list is at 
the bottom of the window; however, you must be aware of when 
you're at the limits and ignore attempts to scroll further. 

A filter function is used to deal with keyboard events. The 
cursor keys on a Mac+ keyboard work as expected, and typing an 
alphabetic character causes the DA to start searching the list for 
the first entry starting with that character (or the first entry 
following if necessary). I don't have full type-ahead, as in the 
standard file selection box, but this was easy to implement and 
still useful. As per the user interface guidelines, the enter and 
return keys return the "accept" button. 

The same lookup routine is used for both dialog windows and 
can easily be extracted for general use elsewhere; I’ve already 
adapted it for multiple use in an application I'me working on 
professionally. 

Data Management; Since the actual processing in the DA is 
rather simple, how to manage the tons of data became the real 
challenge. After discarding several fairly complex indexing 
schemes initially, I settled on using the Resource Manager, 
which worked out nicely. There are 3 basic resource types 
involved: 

(1) Name Lists: The list of manager names, and the lists of 
routine names in each manager, are stored as “КОММ? resources. 

(2) ROM Calls: Each ROM call is stored as a ROMC" 
resource. Each variable is prefixed by its type in a simple 
condensed format. 

(3) Abbreviations: This is the list of expansions for each of the 
data type abbreviations used in the ROM calls. 

Since we are dealing with a large number of resources (there 
are 640 calls in the data file, plus the name lists) and the data had 
to be as compact as possible if it was going to be useful, I used 
several tricks to save space. 

At the start of a ROMN (name list) resource, before the text 
data, there are 2 16-bit integers. The first gives the number of 
lines in the data; this is convenient for setting the scrollbar 
maximum. The second field gives the starting resource number 
for the calls listed, The calls for a manager are numbered 
sequentially from the number listed in the КОММ resource, so 
the resource ID for a call is simply its relative position in the list 


152 


plus the “base” resource number. This avoided having to store the 
resource ID with each individual name (and saved about 1.5K). 
It also means that additional calls and managers can be added at 
any time; simply choose an *unused" range for the new manager. 

ROM Call Formatting: As mentioned above, the ROM call 
prototypes are stored in a simple compressed format. Each call is 
preceeded by a 1-byte flags field; currently, all it indicates is 
whether or not the call is a *memory masher". 

Abbreviations in a call are indicated by bytes with a value of 
$80 or more. These abbreviations fall into 2 classes: $80 - $BF 
are non- VAR datatypes, while the range of $CO - $FF is identical 
to the lower range, but are considered VAR types. An abbrev- 
iation is shifted to the range $0-$3F and used to index into a table; 
this table is simply a “гот abbreviation" (ROMA) resource that 
was loaded during initialization and detached. 

The expansion of an abbreviation is the only difference 
between the *C' and Pascal versions (other than the names of the 
datafiles opened). Being initially written for “С”, the processing 
is simpler for that: simply look up the abbreviation and substitute, 
formatting it as (type *) if itis a ‘var’ variable. The expansion for 
Pascal is more complex, since the VAR and datatype are on 
opposite ‘ends’ of the variable name. 

Clipboard manipulation; this is pretty conventional, except 
for the appendScrap function. This assumes there is only 1 data 
type on the clipboard. Following the data type (a 4 byte field) is 
the length; Icopy the existing text toa working buffer, append the 
new text, and copy the new text back to the scrap, updating the 
length. Simply doing 2 PutScraps will append the text, but not 
update the length, making the new text unaccesable. It would not 
be much more complicated to deal with multiple data types on the 
clipboard. 

Data File Construction: This was, not surprisingly, the most 
laborious part of the project, and changed several times while 
under construction. 

Heavy use is made of macros and assembler variables. 
Macros are created for each datatype, and generate the abbrev- 
iation byte preceeding each formal parameter. Changing the text 
in the ROMA resource corresponding to a given macro will 
change the expansion. I wasn’t entirely consistant with some of 
the subtly different (but functionally identical) datatypes, since 
the typecasting is generally only a reminder and not left in the 
working program. 

Assembler variables are used to automatically generate the 
resource IDs in ascending sequence; the variable at the beginning 
of a sequence is set to allow for “pre-incrementing”. 

The sources for the data file are for the ‘C’ format calls. The 
only real difference between the ‘C’ and Pascal forms 1s that 
Consulair ‘C’ requires all structures to be referenced by pointers, 
even those that are not VAR variables in the Pascal sense. Thus, 
converting the data file to Pascal conventions will simply involve 
removing the VAR status of most structures and rebuilding. 

Construction: is fairly conventional. The DA is built exactly 
as in Don Melton’s article, using his files (with 1 header file 
renamed to reflect a change between Consulair versions). See 
MacTutor Vol. 2 No. 4 (April, 1986). 

The data files are in assembler; they are assembled and then 
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linked to form the final data file. mbling th files i 
quick, but linking seems to take forever, Опа Мас+ with noRAM 
disk, linking the data file takes 8 minutes, although the assembly 
only takes about 1. Don't worry... 

Miscellaneous: I want to thank Don Melton again for his DA 
article; Ihad been having no luck with DAs until then. I also want 
to highly recommend MEdit, by Mathias Aebi; it allows you to 
build editing macros to automate repetitive tasks. When I decided 
to change approaches to the data file, it allowed me to reformat 
about 80K of source in less than 1 hour! 

It should not be difficult to adapt ROMRef into an online help 
facility for the toolbox. After the routine had been selected, the 
routine thatcurrently expands the rom call would bring up a small 
dialog box and display the help text instead. I think the text would 
be rather terse, since the amount involved would be even larger 
than the current file; most likely, a hard disk would be required 
to work with adequate information. A different set of abbrevia- 
tions could be built to compress the most common words in the 
database, and the ‘VAR’ mechanism would be un-needed. If 
anyone does use ROMRef to build such a DA, please put it out 
for the public to use!! 


/* А ROM Reference Desk Accessory */ 


/* Frank Alviani */ 
/* Version 1.1 */ 
/* 8:36:39 РМ 8/5/86 */ 
/* */ 
/* Thanks to Don Melton for making */ 
/* this а whole bunch easier! x/ 


®Options R=4 Z К 
*include «MacDefs.h» 
8include <QuickDraw.h> 
include «Control.h»? 

* include «TextEdit.h» 
8include «Dialog.h? 
®include «Меги. 
8include «Events.h? 

* include «Desk.h»? 
®include «DeskAccessory.c? 
8 include «Resource.h? 


/* MODIFIED DEFINITIONS 


*** IMPORTANT *** Other alternate elements of the OpPar- 
amType union structure are not defined here!!! 


The Спіг1Рагат structure also must be def ined because 
0SIO.h is not included. However, it remains unaltered. */ 


define OsType long 
union __0Р 


ЫЕ, 
short menuID; 
short menuItem; 


) menuData; 
Ptr event; 


"def ine OpParamType union . ОР 
iri —СР 

struct —CP *ioLink; 

short ioType; 
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short іоТгар; 

Ptr ioCmdAddr; 
ProcPtr ioCompletion; 
short ioResult; 

char *ioNamePtr; 
short ioVRefNum; 
short ioRefNum; 

short CSCode; 
OpParamType csp; 


8def ine CntrlPeram struct . CP 
шаса struct 
char typeName[4]; 


) ResType; 
typedef struct ( 
long scrapSize; 
Handle scrapHandle; 
short scrapCount; 
shor t scrapState; 
char *scrapName ; 


) ScrepStuff, *ScrapStuffPtr; 


"def ine NULL 0 

"def ine FALSE 

"define TRUE 1 

"def ine geneva 3 

8def ine NAMES. IN. BOX 7 
"define TIX CClong *) 8x16A) 


#def ine ACCEPT 1 

def ine ACCEPT. CONT 2 
Üdef ine APPEND 3 

"def ine APPEND. CONT 4 
дег ine CANCEL 5 

"def ine NBOX 7 
define SBAR 8 


8def ine FRONT. WINDOW -1 

/* SETUP DA HEADER AND GLUE ROUTINES 

*** IMPORTANT *** Invoke this macro BEFORE declaring any 
global variables or defining any Mac C functions!!! 


Macro parameters: 
Name of desk accessory Cenclose text in single 


quotes) 

2 Resource ID of desk accessory (12-31 inclu- 
sive) 

3 Flags 

4 Delay 

5 Event Mask 

6 Request for global variable allocation: 


NeedGlobals or NoGlobals 
x 


Ваза 
DeskAccessory ‘ROM Ref’, 12,90400,0,%0142 NeedGlobals 
*endasn 


/* GLOBAL VARIABLES */ 
short ownedID; 


short no_casting; /* Ø=typecast 1-don't typecast */ 
short mem mash; /% i=include comment */ 
short selection; 


MenuHandle hRRMenu; 
DialogPtr abtDigPtr, mgrDigPtr, rtnDlgPtr; 
long lestCl ick; 


short lastP ick; /* double-click test */ 
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short data_refNum; /% vol ref num data file */ 
short old.v; /* for arrow-scrolling */ 
ControlHendle rtnScriH, пәтӛсгінН; 

/* scroll bar in routine window */ 
ControlHandle — vScr1H; 

/* “generic” for ModalDialog filterProc */ 
Handle abTblH; /% handle to abbreviation table */ 
TEHandle hTE; /* for names selection routine */ 
Rect textR, TERect; 
char ca11[256]; /* sample here */ 
ScrepStuffPtr — sInfo; 


/*"O0pen/Close/Control" - Open Routine - */ 
Short open(pb, dce) 

Спїг1Рагат зрб; 

DeviceControl асе; 


GrafPtr oldPort; 

short item, type, err, def vol; 
ControlHendle сіН; 

Ptr tPtr; 

short pbCa11C2; 


ownedID = 0хС000 - (32 * (1 + асе-› dCtlRefNum)); 
dce-?dCtlMenu = ownedID; 


if Cidce— dCtlWindow) 
( hRRMenu = GetMenuCownedID); 
HNoPurgeChRRMenu 2; 


if C!CmgrD1gPtr = (DialogPtr) 
NewPtr(sizeof (DialogRecord)))) 
return -1; 
mgrDlgPtr = GetNewDialogCownedID, mgrDigPtr, 
FRONT_WINDOW); 
GetDItem(mgrDlgPtr, SBAR, &type, &nemScr|H, &textR); 
/* scrollbar */ 
namScrlH = NewControl(mgrDigPtr, &textR, “\рх”, 
FALSE, 0, 0, 0, ѕсго11ВагРгос, 0); 
if C!drtnDlgPtr = CDiaelogPtr) 
NewPtr(Csizeof (DialogRecord)))) 
return -1; 
rtnDlgPtr = GetNewDialogCownedID* 1, rtnDigPtr, 
FRONT_WINDOW); 
GetDItem(rtnDlgPtr, SBAR, &type, &rtnScrlH, &textR); 
/* scrollbar */ 
гіпбегіН = NewControl(rtnDigPtr, &textR, “\px’, 
FALSE, 0, Ø, 0, scrollBerProc, 02; 
GetDItemC(rtnDlgPtr, NBOX, &type, &ctlH, &textR); /% 
get scrollBOX rect */ 
TERect = textR; 
InsetRectC&TERect, 2, 2); 
if C!CebtDIgPtr = CDialogPtr) 
NewPtr(Csizeof (DialogRecord)))) 
return -1; 
ebtDigPtr = GetNewDialogCownedID*2, abtDigPtr, 
FRONT..N INDOW); 
/* open data file */ 
if CCdata_refNum = OpenResF ileC^MpRom Reference 
Deta^)) == -1) 
return -1; 
if CCebTblH = GetResourceC'ROMA^, 1)) == NULL) /* 
get abb. table */ 
return -1; 
no.casting = 0; mem mesh = 0; 
activate); 


return 9; 
/* - Close - */ 
dut close(pb, dce) 


Cntr 1Param *pb; 
DeviceControl асе; 
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deActivate(); 

ReleaseResourceChRRMenu); 
ReleaseResourceCabTb1H2; 
DisposeDialog(mgrDlgPtr); 
DisposeDialog(rtnDlgPtr); 
DisposeDialogCabtDlgPtr); 

dce-?dCtlWindow = CWindowPtr) NULL; 
CloseResFileCdata.refNum); /* close data file */ 
return 0; 


) 


/* - Control - */ 

short control(pb, dce) 
Cntr 1Param *pb; 
DeviceControl “ссе; 


EventRecord *theEvent ; 


switch (pb-?CSCode) 
( case accEvent: 
theEvent = CEventRecord *) pb->csp.event, 
if CtheEvent->what ==activateEvt) 
if (theEvent modifiers & activeF lag) 
activate(); 
break; 
case accMenu: 


doMenu(pb, pb-»>csp.menuData.menultem, dce); 
break; 


return 9; 


activate ) 


C*hRRMenu2-?menuID = ownedID; 
Inser tMenuChRRMenu, 0); 
DrawMenuBer( ); 


deActivateC) 


DeleteMenuCowned ID); 
DrawMenuBar ( ); 


/**Menu Stuff~ — Handle Menu Invocations - */ 
doMenu(pb, menuItem, dce) 

Cntr 1Param зрб; 

short menuItem; 

oo *dce; 


short thel tem; 
GrafPtr tGPtr; 


Switch (menu! tem) 
( cese 1: /* ABOUT */ 
dce- dCtlFlags &= OxFBFF; /* clear dCtlEnable */ 
dce-?dCtlFlags “= 0х4000; /* set dNeedLock */ 


(CWindowPeek) abtDlgPtr)- windowKind = 2; /% 


dialogkind */ 


ShowWindowCabtD1gP tr); 
BringloFrontCabtDlgPtr ); 
SetPortCabtDigP tr); 

ModalDialog(NULL, &theItem); 

CCWindowPeek) abtDlgPtr)-?windowKind = dce- 


»dCt 1RefNum; 


HideWindowCabtD1gPtr); 


dce->dCtlFlags “= 0х0400; /* set dCtlEnable */ 
дсе-›асіЛЕЛадѕ &= OxBFFF; /* clear dNeedLock */ 
break; 
case 2: /* LOOKUP CALLS */ 
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dce— dCtlFlags &= OxFBFF; /* clear dCtlEnable */ if Citem == ACCEPT_CONT || item == APPEND. CONT) 
dce— dCtlFlags “= 0х4000; /* set dNeedLock */ /* keep it up! */ 
goto get mgr; 


findRtnCdce); 
dce— dCtlFlags “= 0x0400; /* set dCtlEnable */ /* - essumes port is properly set before entry - */ 
бсе-› аСіЛЕТадѕ &= OxBFFF; /* clear dNeedLock */ /* - returns item_no from modal dialog box - */ 
break; short BoxPick(dPtr, scrlH, resNo, sel, base) 
cese 3: /* DISABLE TYPECASTING */ DialogPtr dPtr; 
if (no.cesting) /* was NO, now YES */ ControlHendle <сгіН; 
( no_casting = 0; short resNo; 
CheckItemChRRMenu, 3, FALSE); short *sel;  /* zero-besed! */ 
) short *base; 
else 
( no_casting = 1; short filter(); 
CheckI temChRRMenu, 3, TRUE); Handle nameListH; /* handle to names-list res */ 
long call_len, nameList_len, ticks; 
break; shor t res.ct, done, item, 1.no, sel.st, sel_en; 
cese 4: /* INCLUDE ‘MASHES MEMORY’ COMMENT */ Point pt; 
if (mem mash) 
nem mash = 0; if CCnameListH = GetResourceC'ROMN^, resNo)) == NULL) 
CheckItemChRRMenu, 4, FALSE); ( SysBeep(60); 
) return CANCEL; 
else 
( mem mash = 1; nameList len = SizeResource(naneL istH); 
CheckItemChRRMenu, 4, TRUE); HLock(nameListH); 
res.ct = *(Cshort *) *nameListH); 
break; /* ct of call resources */ 
case 5: /* CLOSE */ *bese = *(Cshort *) *nameListH* 15; 
close(pb, dce); /* starting call res * is 2nd short! */ 
break; 
hTE = TENewC&TERect, &TERect); 
HiliteMenuC0); C*hTE)-> txFont = geneva; 
C*HTE)->crOnly = -1; /* CR breaks only */ 
СҰҺТЕ)-› txSize = 12; 
/*"Lookup Code" - Heart of the DA - */ TESetText(*nameListH+4, nameList_len-4, ҺТЕ); 
f indRtn(dce) TECalTextChTE); 
DeviceControl хасе; TESe tSelect((*hTE)-> lineStarts(0)], C*hTE2-»lineS- 
tarts({1], ҺЕ); 
shor t the-manager, item, base_res_no, pick; 
Tong Screp.err, call len; CCWindowPeek) dPtr2)-»windowKind = 2; 
short BoxPick(); showW indow(dP tr); 
BringToFront(dPtr); 
get mgr: FrameRect(&textR. top); 
/* use “select manager” dialog */ TEUpdateC&TERect.top, hTE); 
dce-?dCtlWindow = 0; TEActivateChTE); 
/* get titles for selected manager */ ShowControlCscr 1H); 
SetPort(ngrD1gPtr); SetCtlMinCscrlH, 0); 
item = BoxPick(mgrDlgPtr, namScrlH, 99, &the manager, if CC*hTE)->nLines > NAMES ІМ. ВОХ) 

&base. res. no); /* set up scrollbar */ 
HideWindowCmngrDlgPtr); SetCtlMaxCscrlH, C*hTE)-»nLines-NAMES IN. В0Х); 
if Citem == CANCEL) return; else 

SetCtlMaxCscrlH, 0); 
/* get titles for selected manager */ SetCtlValueCscrlH, 0); 
se tPor t(rtnDlgPtr ); 
item = BoxPick(rtnDlgPtr, rtnScrlH, the_manager+1, done = FALSE; selection=9; 
&pick, &base_res_no); old.v = 8; 
if Citem « CANCEL ) vScrlH = scr H; 
( expandCall(base_res_notpick, &cell. len); while C!done) 
if Ccall.len) ( ModalDialog(filter, &item); 
( if Citem « APPEND ) /* filter for keystrokes only */ 
( ZeroScrap(); switch Citem) 
scrap_err = PutScrap((long) call. en, ( case ACCEPT: 
‘TEXT’, call); case ACCEPT_CONT: 
) case APPEND: 
else case APPEND. CONT : 
AppendScrap((long) call .len, ‘TEXT’, call); case CANCEL: 
done = TRUE; 
) break; 
case NBOX: 
CCWindowPeek) rtnDlgPtr2-»windowKind = dce- Ge tMouse (&pt ); 

»dCt 1Ref Num; ticks = *TIX; 

HideWindowCrtnDlgPtr); 1-ло = (pt.v - textR. top) / СҰҺТЕ)-› 


lineHeight; /* relative line? */ 
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selection = GetCtlValueCscrlH) + 1.no; 
if CClestClick + 30) > ticks) 
( item = ACCEPT; 
/* double click in seme item */ 
done = TRUE; 
break; 


sel_st = (*hTE)-?lineSterts[selection]; 
if (selection >= res.ct) 
sel_en = 32767; 
else 
se]_en=(*hTE)-> lineStar ts[selectiont1]; 
TESetSelect(sel_st, sel_en, ҺЕ); 
TEActivateChTE); 
lastPick = selection; 
lastClick = ticks; 
break; 
case SBAR: 
nameScrol1(dPtr ); 
break; 


) 
TEDisposeChTE); 
HUnlock(nameL istH); 
Re leaseResource(nameListH); 
*sel = selection; 
return item; 


) 


/* - Append to scrap,updating screpCount-Memory Only - */ 
/* essumes only 1 dete type in desk screp */ 
AppendScrap(Clen, type, str) 


long len; 

long type; /% 4-char string */ 
"nd *str; 

long sSize, dSize; 


sInfo = (ScrapStuf fPtr20x960,; 
if CsInfo->»scrapState <= 0) return; 
/* can’t do anything */ 
sSize = GetHendleSizeCsInfo-?screpHendle); 
dSize = *(Clong *)¢*sInfo->scrapHandle) + 1); 
/* get existing len */ 
SetHandleSize(sInfo->»scrapHandle, sSize + len); 
/* make room */ 
*(Clong *)(*sInfo->scrapHandle) + 1) = dSize + len; 
BlockMove(str, (*sInfo- screpHendle + 8 + dSize), len); 


/**Scrolling™ - Filter Events, Handle Scrolling, etc. - */ 
short filter(dPtr, ePtr, item) 


DialogPtr dP tr; 

EventRecord *ePtr; 

short хі (еп; 

Ваза 
link AG, 10 70 locals 
movem. | D1-D2,-Csp) j save 
move. 1 16(А62,00 
поуе.1 12(А62,01 
move. | 8САб ),02 
jsr nd filter ;call С routine 
movem. 1 ($Р)+ ‚р 1-02 
ил1К Аб 
move. 1 CSP )+, Аб ;return addr 
edd.1 н 12,sp 
move.b 00, CSP) ;,return condition 
jmp CAB) 

Sendasa 


/* uses global “уӛсгіН” to access vertical scrollbar іп MD 


window */ 
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short adfilter(dPtr, ePtr, item) 


DialogPtr dPtr; 

EventRecord *ePtr; 

oo *iten; 

short pert, new. v, i, j, К, OV; 

short sel_st, sel.en, delta; 

cher ch, ch2, key; 

Ptr tPtr, base; 

short nameScro11(); 
switchCePtr-> what) 


( case mouseDown: 
return FALSE; /* handle normally */ 
break; 
case autoKey: 
case keyDown: — /* select by ist letter, cursor 


keys, etc. */ 


ch = ePtr-?messege & OxFF; 
if Ссһ==0х03 || сһ==0х00) /% ent or ret */ 
( *item = 1; /* accept */ 
return TRUE; 


/* check for up/down arrow keys */ 
if Cold.v <= GetCtMaxCvSer 1H2) 
/* don’t update if in lest paneful */ 
old.v = GetCtlValueCvScr1H); 
j = GetCtlMexCvScr 1H2; 
TEDeact ivateChTE); 
TESetSelectC0, 0, NTE); 
key = CePtr->message & OxFF00) >> 8; 
if (кеу == 0х40) /* up arrow on Mac* */ 
( i = old_v-1; 
if Ci < Ø) ї = Ø; 
goto qal; 


if (кеу == 0x48) /* down arrow on Мас+ */ 
(і = old.v + 1; 
goto qal; 


/* look up ist entry starting with given key or higher */ 
ch &= (*8x28); — /* force uppercase */ 
HLock( C*hTE)->hText); 

/* lock text for examination */ 
base = *(*hTE)->hText; 
for (iz8;i«j; i++) 
( tPtr = base + (*hTE)-) lineStarts[ i]; 
ch2 = *tPtr & (C"0x20); 
/* ist cher of line, upper-cased */ 
if (ch2 >= ch) 
/* found desired line */ 
break; 


HUnlockCC*hTED-»hText2; 
qal: 
if Ci <= j) /* in normal range, scroll! */ 
( dV = Cold_v - 1) * (*hTE)-?lineHeight; 
SetCtlVelueCvScrlH, i); 
TEScrollC0, dV, ҺТЕ); 


if Ci >= GetCt1MaxCvScr 1H)*NAMES. IN. BOX) 
( i = GetCtMaxCvScr 1H) *NAMES.-IN. BOX- 1; 
/* can’t go too far */ 
sel_en = 32767; 
k = (*hTE)-»nLines-1; 
sel.st = (*hTE)-> lineStarts[k]; 


else 
( selen = (*hTE)-> lineStartslit1]; 
sel.st = (*hTE)-) lineStarts[il; 


) 
TESetSelect(sel.st, sel_en, hTE); 
Old_v = i; 
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selection = i; 
/* in global so ACCEPT works */ 
TEActivateChTE); 
return TRUE; 
break; 
default: 
return FALSE; 
break; 


) 


void nameScrol 1(dPtr) 
DialogPtr Ptr; 


short part, new_part, old_v, new _v, dV; 

ControlHendle ctiH; 

Point pt; 

void scroll_up(), scroll_dn(); 
GetMouse(&pt); 


if (part = FindControlC&pt, dPtr, &ct1H)) 
( old_v = GetCtlValueCct1H); 
switch (part) 
( case inThumb: 


пеи рагі = TrackControl(ctlH, &pt, NULL); 
if (пен. рагі == pert) — /* redraw box */ 


( TEDeactivateChTE); 
new_v = GetCtlValueCct1H); 


dV = Cold.v - new.v) * (*hTE)->lineHeight; 


TEScro11C0, dV, ҺТЕ); 


break; 

case inUpButton: 
TreckControlCctlH, &pt, scroll.up); 
breek; 

сазе inDownButton: 
TreckControlCct]H, &pt, scroll. дп); 
break; 

case inPageUp: 
new.v = old.v - (NAMES. IN. BOX- 1); 
if Cold_v-new_v < 0) 


( dV = old.v * (*hTE)-? lineHeight; 
/* stop at beginning */ 
SetCtlValueCctlH, 0); 


else 
( dV = (NAMES ІМ BOX-1) * (*hTE)- line- 


Height; 
SetCtlValueCctlH, new_v); 


ТЕӘсго11(0, dV, ҺТЕ); 
break; 
case inPageDown: 
new_v = old_v + (NAMES IN. BOX- 1); 
if Cnew_v > GetCtlMaxCct1H2) 
(ау = -CGetCtMaxCct]H) - old_v) * 
C*HTE)-> 1 ineHeight; 
SetCtlValueCct]H, GetCtMaxCct1H22; 


else 
( dV = -CNAMES_IN_BOX-1) * C*hTED- 
› lineHeight; 
SetCtlValueCctlH, new_v); 


ТЕ5сго11(0, dV, ҺЕ); 
break; 


selection = new. v = GetCtlValueCct1H); 


TESetSelectCC*hTE2-» lineStarts[new.v], C*hTE)- 


»lineStarts[new.v*1], ҺТЕ); 
TEActivateChTE); 
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void ay-scroll.up(theControl, part) 
ControlHendle ^ theControl; 
short pert; 


short wv; 


if (pert == inUpButton)  /* */ 
( v = GetCtlValueCtheContro1); 
if (v == 8) return; 
SetCtlValueCtheControl, v-1); 
ТЕбсго11(0, C*hTE)-»lineHeight, ҺТЕ); 


return; 

Заза 

scroll_up: 
MOVE.L (SP2*,A0 ; RETURN 
MOVE.W CSP)+,D1 ;PART 
MOVE.L (SP2*,D0 ;CTL HANDLE 


MOVE.L Ай,-($Р) 
MOVEM.L АЗ-А4/03-07,-СӨР) 


JSR ny-scroll.up 
MOVEM.L CSP2*,A3-A4/D3-D7 
RTS 

Sendasa 


void ay.scroll.dnCtheControl, part) 
ControlHendle theControl; 
short pert; 


short v; 


if (pert == inDownButton) 
( v = GetCtiValueCtheContro12; 
if (v == GetCtlMexCtheContro12) return; 
SetCtlValueCtheControl, у+1); 
TEScroll(8, -C*hTE)-» lineHeight, hTE); 


) 
return; 
Заза 
Scro11. dn: 
MOVE.L (SP)+ AØ ; RETURN 
MOVE.W (SP)+,D1 ;PART 
MOVE.L (SP)+,DØ ;CTL HANDLE 


MOVE.L A®,-CSP) 
MOVEM.L АЗ-А4 /03-07 , -CSP) 
JSR my_scro}1_dn 
MOVEM.L CSP2*,A3-A4/D3-D7 
RTS 

у 948 


/*"Prototype Expension" – Resource -> usable call - */ 
void expandCall(res.no, len) 


short res no; 

long *len; 

Handle rHndl; 

short i, j, isVar; 
long rSize; 


unsigned cher — *rPtr, ch, abb(32]; 


if С(гНпа1 = GetResourceC'ROMC^, res.no)) == NULL) 
( SysBeep(30); 
*len = 0; *call = NULL; 
return; 


rSize = SizeResource(rHnd1); 
HLockCrHnd1); 

rPtr = (unsigned char *) *rHnd1; 
HLockCabTb1H); /* lock ebb. table */ 


/* deal with “memory mashing’ */ 
2:0; 
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x 
x 
x 


if (nen mash) 
( if (*(гР{г++)) 
eppStr(^/* mashes memory */ *, call, &j) 


else 
rPtr += 1; /* just skip flag */ 
for Ci=1; i<rSize; it+) 
/* copy into output, expanding abbreviations */ 
( if (*rPtr < 0x80)  /* normal char */ 
( calll(j++) = *(rPtr++); 
continue; 


if Cno_casting == NULL) 
( if C*rPtr >= 0хС0)  /* “маг” */ 
| isVer = 1; ch = *rPtr - 8x40; 


else 
і isVar = 8; ch = *rPtr; 


са11(3++] = 'C*5; 
f indebb(ch, abb); 
eppStrCebb, &Cca11LjD, 8); 
if CisVer) 

( calltj**1 = * *; calllj++] = 4%); 


са111}++1 = “)/; 


rPtr += 1; 


eppStrC^; M^, &(са11[}]), &j5; 
*len = j; 

HUnlock(CrHnd12; 
HUnlockCabTb1H2; 
ReleaseResource(CrHnd1); 


) 


void appStr(src, target, еп) 
char *src; 
char *target; /* string appended TO */ 
short Жеп; 


long сі-0; 
Ptr tp; 


tp = src; 
while C*Ctpt*)) 
ctt+; 
BlockMoveCsrc, target, ct); 
*tLen = *tLen + ct; 


) 


void findabb(c, dest) 
unsigned cher c; 
unsigned char — *dest; 


short i,j; 
Ptr tPtr; 


{Ріг = *abTblH; 
j = c - 0x80; 
for (i20;i1«j;i1**) 

while (*(tPtr++)); 
while C*tPtr) 

*(dest**) = *CtPtr**); 
*dest = NULL; 


Resource file for the ROM Ref DA 
Frank Alviani 
3:50:20 PM 6/6/86 


RomRef DA:Rels:RomRef .rsrc 
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/* this one moves memory */ 


/* lookup typecast */ 


/* string copied FROM, null-terminated */ 
/* initial length of target; updated */ 


* Menus 
Type MENU 

," 16000 
Тоо1Вох 
About Myself.. 
Lookup Calls 
Diseble Typecest ing 
Show Memory Mashers 
Close 


x 
* Manager Selector box 
x 


TYPE DLOG 
, 16200 


x 

TI 62 239 451 
InVisible NoGoAway 
1 


0 
-16000 


ТҮРЕ DITL 
,716000 
8 


BtnItem Enebled 
68 265 94 383 
Accept 


BtnItem Enabled 
*38 264 64 383 

1000 1000 1001 1001 
Accept/Cont inue 


BtnItem Enabled 
*68 265 94 383 
1000 1000 1001 1001 


Append 


BtnItem Enebled 
98 265 124 383 
1000 1000 1001 1001 
Append/Continue 


BtnItem Enabled 
98 265 124 383 
Cance] 


StatText Disabled 
6 8 22 251 
Select a ROM Manager 


* TextBox 
User Item Enabled 
34 10 151 223 


* Scrol 1Box 
UserItem Enabled 
34 222 151 238 


x 


(#1) 


* Routine Selector box (#2) 
x 


TYPE DLOG 
,- 15999 


x 

77 62 239 451 
InVisible NoGoAway 
1 


0 
-15999 
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TYPE DITL 
,- 15999 


8 

BtnItem Enabled 
8 264 34 383 
Accept 


BtnItem Enabled 
38 264 64 383 
Accept /Cont inue 


BtnItem Enabled 
68 265 94 383 
Append 


BtnItem Enabled 
98 265 124 383 
Append/Cont inue 


BtnItem Enabled 
128 265 154 383 
Cance] 


StatText Disabled 
6 8 22 251 
Copy а sample call to the clipboard 


* TextBox 
UserItem Enabled 
34 10 151 223 


x ScrollBox 
UserItem Enabled 
34 222 151 238 


x 
* About box (83) 
x 


type DLOG 

‚715998 

х 

48 62 314 451 
InVisible NoGoAway 
1 


0 
- 15998 


{уре DITL 

,7 15998 

15 

BtnI tem Enabled 
238 301 264 380 
OK! 


StatText Disabled 
10 69 26 319 
ROM Ref: Online Toolbox Call Samples 


StatText Disabled 
36 10 52 384 
ROM Ref allows you to put 1 or more sample ROM calls 


StetText Disabled 
52 10 68 384 


on the clipboard to be pasted directly into the progrem. 


StatText Disabled 
68 10 84 384 
When you select 'lookup^, you аге presented with а list 


StetText Disabled 
85 10 101 384 
of ROM managers. When you pick one, a list of all the 
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/6 


/0 
/Т 


StatText Disabled 
101 10 117 384 
calls is presented. ‘Accept’ puts the selected call on the 


StatText Disabled 
118 10 134 384 
Clipboard and quits; ‘accept/continue’ then returns to 


StatText Disabled 
135 19 151 384 
the manager list. ‘Append’ adds the selected call to the 


StatText Disabled 
152 10 168 384 
clipboard so several can be copied at once. Typecasting 


StatText Disebled 
169 10 185 384 
can be disabled. A comment can be added for every call 


StatText Disabled 
186 10 202 384 
that can scramble memory. 


StatText Disabled 
215 10 231 106 
Frank Alviani 


StatText Disabled 
231 10 247 114 
425 McAlister 


StatText Disabled 
248 10 264 159 
Waukegan, 111 68085 


RomRef Link File 
lobals -$9 


utput ROMRef 
ype ‘DFIL’ ‘DMOV’ 


/NoStrip 


/R 
Ro 


/1 


[End 


esources 
mRef .rel 


nclude RomRef .rsrc 
[Please note that the 


Inside Macintosh defini- 
tion files necessary to fully 
support this DA are in- 
cluded on the source code 
disk as a series of format- 
ting files which define how 
the DA is to set up the IM 
calls. The length of these 
files is too long to be in- 
cluded here, but if you wish 
to fully implement this DA 
as an IM reference, you 
might want to purchase the 
source code disk for this 
issue to have access to 


these files that Frank has 

provided. See the Mail 

Order Store ad for details 

on ordering the source = 

code disks. -Ed] |954, 
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Programmer's Workshop 
Pascal String Library for C 


Breaking away from C strings and the Stdio Library 

Many Mac C programmers use C style strings in order to 
remain compatible with the Stdio library which provides several 
commonly needed functions. Unfortunately, C strings are in- 
compatible with virtually all the ROM routines that take strings 
asarguments. I will pointout the draw backs to the mostcommon 
solution to this compatibility problem and then discuss how to 
eliminate it altogether. 

In this process, I will show you how to create libraries of code 
in such a way as to allow LightspeedC to link only the code that 
was actually used, as well as give you examples of how to use 
Apple's SANE, Str2Dec and Dec2Str libraries. I will also 
demonstrate how to write functions in C that take a variable 
number of arguments. More importantly, I have provided the 
source for a complete Pascal String Library. 

Need for a Pascal String Library 

The easiest way around the string compatibility problem is to 
use the MacTraps routines CtoPstr() and PtoCstr() to convert 
back and fourth between C and Pascal strings at run time. 
However, using these extra function calls will increase the size of 
your code and may hinder your application's overall perform- 
ance since it takes time to do the conversions. Including the Stdio 
library adds approxiamtely 16K to your application alone. 
Couple this fact with the string conversion overhead neccessary 
to stay on speaking terms with the ROM, and you've got a real 
mess! 

You could eliminate the problem altogether by using Pascal 
strings, exclusively. This implies having to write your own code 
as a functional replacement for the Stdio library. How dependent 
are you on the Stdio? Since getchar() and printf() are next to 
useless in the Mac environment, there are really only two areas 
of concern—file and Pascal string handling. 

Reading the File Manager chapter of Inside Macintosh will 
get your wheels rolling in the file handling department. It is very 
easy to create, delete, open, close, read and write files using the 
ROM routines. If you need examples of how to use the routines 
and you can't find them anywhere else, you can always dig 
through the Stdio's source code. Yes—even the Stdio uses the 
ROM! Implementing a high quality Pascal String Library is not 
as easy, so I have taken this burden off your shoulders by 
providing one for you. 

Writing the functions to draw, copy, concatenate and search 
Pascal strings was fairly straight forward. It is important to 
remember that type ‘char’ is actually a signed quantity and that 
character values greater than 127 will be considered negative. I 
gotaround this “feature” by declaring all Pascal string arguments 
as ‘unsigned char %” (i.e. a pointer to an unsigned char). Тһе 
signed quantity issue was particiliarly important for the PSuFind 
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e Pascal String Library Demo • 


The following pages will explain the 
'How To's and the 'Resuits Of' using 
each function in the Pascal String Library. 


Page 1 


Fig. 1 Demo shows how to use the string library 


functions which take 'char's as arguments. Since all K&R 
standard C compilers convert ‘char’s to ‘int’s before passing 
them toa function, I declared the argumentas type ‘int’ within the 
function definition and then manually stripped the sign extension 
off via: int var &= OxFF; 

Immediate char values such as ‘°° DO NOT get sign extended! 
During a few moments of carelessness, you could easily write a 
function that works correctly with ‘immediate’ character argu- 
ments, but FAILS when tested with ‘char’ type arguments! Note 
that sign extension of type 'char' (i.e. or any other signed type) 
occurs BEFORE а cast takes affect, so casting type ‘char’ to type 
‘unsigned int’ for example will not solve the problem. 

(In hopes of reducing redundant expressions, I will hence- 
forth substitute “standard type” in place of “type int, long, float, 
short double and double") 

Writing the functions to: 1) create a Pascal string represen- 
tation of any standard type of number. 2) set the value of any 
standard type of number to the value represented in a Pascal 
string—was far more challenging. Rather than writing seperate 
functions for each type of number, I wrote two functions capable 
of operating on any standard type. This was made possible by 
using the SANE, Dec2Str and Str2Dec libraries! 

SANE Contributions 

There are two structures defined in the sane.h file which you 
need to be aware of in order to understand these libraries. 
Decimal structures are used to store decimal string representa- 
tions of numeric values in up to 20 digits of precision. DecForm 
structures are used to specify the number of significant digits and 
whether you want a FLOATDECIMAL (i.e. scientific notation) 
or FIXEDDECIMAL (i.e. decimal) representation of a value. 

SANE provides procedures to set a Decimal structure equal 
tothe value of any standard type of number, as well as procedures 
to setthe value of any standard type of number equal to a Decimal 
record. The Dec2Str library provides a procedure to create a 
Pascal string representation of a value in a Decimal structure 
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PS ( t, s, h, v, ) SetFont (font, size, face) 

trÜree ‘count, INE 

count 9 of (в, h, v) arguaent sets to follow. _ | 
Meal ‘airing to cree інші - асе 
Horizontal coordinate foce - Font style 
Vertical coordinate 


2-9 additional sets of ( s, h, v) SetFont() sets the txFont, txSize and 


PStrDrow(? draws 1 to 10 Pascal strings at specified locations in Сесе fields of the current OrefPort. 


the current GrafPort. it Offers auto-center ing and New-Line aodes. 

if h эз O then it uses the last (current) h position. 

if v 0 then it uses the last (current? v position. 

If x < 0 string is centered inside portBect. If y < 0 . 

string is offset -y lines from last (current? v position. Liste E eee дей 

Othereise, h and v represent the desired x and y coordinates. Техќ812е(9): ? 
«« This drawn by... >> TextFace(bo!d?; 

---Calling: — PStrOraeCt, "Ap«« This was drawn by... >>", CEN, NL15; , 


Pege 2 


Previous INE кені 


pa 
ta 


Calling: 
SetFont(aonaco, 9, bold); 


( Language | | | E 1 ( Language 


Mun2PStr (type, naPtr, s, foraat, places? PStr2itue (s, type, maPtr) 


CINT. CLONG ССОРР, CFLOAT CSHORTDEL, COBL s - Pascal string representation of a number 
е. Address of & given type of nubes type - CINT, CLONG, CCOMP, CFLORT, CSHORTDBL, CDBL 
s - Pascal string to recieve the string representation nuaPtr - Address of a given type of number 
foreat - DEC or SC! <deciaal or scientific notation) 
places - Number of decimal places desired in representation PStr2NuaC) sets a given type of number equal 
to the value represented in the pascal string s. 
Nua2PStr¢> creates a pascal string representation of a given 


type of number in either deciaal or scientific notation. Given: 51347255 e» "ip- 123456789 . 96765432 1° 
Calling: PStr2Nua(s1.Str255, CDBL, Gadouble); 


Given: a_double == -987654321.997654321 Results in:  a.double == - 123456789 .987654321 
Calling: Num2PStr<(COBL, ба double, s1.Str255, DEC, 9); 
Results in:  si.Str255 == °\p-087654321. 987654321" 
Calling: Mua2PStrCCDBL, &o double, s1.Str255, SCI, 17); 
Results in:  si.Str255 == “\p-9.8765432 198765432 1e+8" 
Page 4 


(СС Qut ^) CShowvars ) (Previous ) (C Nent y) 


( Language | : : С Language 
PStrCopy (src, pos, count, dst) PStrCet (count, dst, ...2 


src Source pascal string count Number of string arg. present INCLUDING dst 
pos Character position in src to start copying dst Destination pascal string 
count Number of characters to copy 424% 1-29 additional pascal string arguments 
dst Destination pascal string 
PStrCat(> concatenates 1-29 additional pascal strings onto dst. 
PStrCopyC? copies count characters (гоа 
character position pos of src to dst. Given: $1.Str255 == “\pThanks for" 
Calling: PStrCat(3, s1.Str2355, "Np the hot", “\ptip!”); 
Given: s1.8tr255 == “\pThis is а pascal string" Results in:  si.Str255 == “\pThanks for the hot tip!" 
Calling: PStrCopy(s1_Str255, 1, ALL, в2.5%,255); 
Results in:  s2.Str255 == “\pThis is a pascal string" 
Calling: PStrCopy(s2_Str255, 11, 6, в1.5%,255); 
Results in: 61.5(г255 == “\ppascal” 


Previous 


C Language C Language 


PStrins (src, dst, ров) PStrÜe! (s, pos, count) 
Pascal string to insert into dst 

dst Destination pascal string (recieves insertion) 

pos Character position of insertion in dst 


Разса! string recieving deletion 

Character position to start deleting 
count Number of characters to be deleted 
PStrinsC) inserts src at pos into dst. PStrDel(> deletes count characters starting at pos froa s. 
Given: s1.Str235 == “\pThat is nice." 
Calling: PStrins<*\pvery ", s1.S8tr25S, 9); 
Results in: s1-Str 235 "\pThat is very nice." 


Given: s1-Str233 == “\pHe has not finished." 
Cal ling: PStrDelcs1-Str255, 8, 4); 
Results in:  si.Str2535 “\pHe has finished." 


Сен) NN 
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according to the settings of a DecForm structure. The Str2Dec 
library provides a procedure to set a Decimal structure to the 
value represented in a Pascal string. These procedures are 
documented in the Apple Numerics Manual. I used them to 
create the PStr2Num() and Num2PStr ) functions listed below— 
notice how little code was required! 
Functions with Variable Arguments 

LightspeedC generates code that uses a calling convention 
designed to allow programmers to write functions accepting a 
variable number of arguments: 
; High memory 
; Callers Code looks like this 


MOVE . . ., -ОӨР) ; lest argument 

MOVE ..., -CSP) ; first argument 

JSR function 

ADD #. . ., -(SP) ; total size of arguments 


; Functions’s code looks like this 


LIN Аб, 8.. . 3; (optional) 
MOVE . . ., DØ ; result 
ОМК Аб ; Coptional) 


; Low memory 

The first argument passed to a function is always in the same 
location relative to the stack pointer (register A7) regardless of 
how many additional arguments are supplied. Thus, all the 
arguments can be found by adding positive offsets to the address 
of the first which is usually an integer specifying how many 
arguments are to follow. The responsiblity of removing the 
arguments from the stack lies with the party that knows how 
many arguments were actualy passed—the caller. The PStrCat() 
and ShowVars() listed below are examples of functions written 
to accept a variable number of arguments. In LightspeedC, the 
maximum number of arguments is 31. 

Fooling LS C into using Strip-able Code Libraries 

LightspeedC's linker considers libraries built with ‘Build 
Library...' command as ATOMIC code units. If any code is used 
then the ALL the code gets linked! Ifa library is itself a project, 
however, then all the source files and libraries with in it are 
individually eligible for removal. This is the key to creating 
*strip-able' code libraries in LightSpeed C! All you have to do 
is: 1) create a seperate source file for each function 2) create a 
new projectand add all the files 3) compile the files. Youcannow 
consider this project a ‘libary’ and include it in any other project 
you want. 

String Library Demo Shows How to Use It! 

Ihave also provide the source for an application that DEMO's 
the Pascal String Library. It’s basically an online tutorial that 
explains the ‘how to's and ‘results of using each function in the 
library. 

You can find stuff like this only in MacTutor! I would like to 
thank David Smith for allowing me to share this information with 
you. Until next time... 


/* File: PStrLib.h */ 
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= PSr SSS 
1 Dec2Str Lib 
: macros сһағ.с 
] Num2PStr.c 

{ PStr2Num.c 

] PStrCat.c 

: PStrCmp.c 

: PStrCopy с 

] PStrDel.c 

] PStrDraw.c 

{ PStrFind.c 

d PStrFindFC.c 

d PStrFindFNS.c 
d PStrFindFS.c 

| PStrFindLC.c 

] PStrFindLS.c 

: PStrFixLen.c 

] PStrins.c 

: PStrRep.c 

a SetFont.c 

] ShowVars.c 

] Str2Dec.Lib 


Fig. 2 The String Library Project 


ifndef _PStrLib_ 

8Sdefine _PStrLib_ 

ifndef .WindowMgr.. 
include <WindowMgr .h» 

Sendif 

8ifndef FontMgr— 
8include <FontMgr .h» 

Sendif 

8ifndef  saneh.. 
8include <sane.h) 


"endif 

extern char —char[); 

#def ine BOOL 1 
"define CDBL FFEXT 
"define CSHORTDBL FFDBL 
"define CFLOAT FFSGL 
"def ine CINT FFINT 
def ine CLONG FFLNG 
“define CCOMP FFCOMP 
def ine PSTR 2 

def ine DEC FIXEDDECIMAL 
“define SCI FLOATDECIMAL 
def ine ALL 255 
define NIL eL 

def ine CEN (-1) 
"idef ine NL1 (-1) 
8def ine NL2 (-2) 
"define CUR (-3) 
"define plain t 
“define -alpha 1 

"def ine -digit 2 

tidef ine hex 4 
define -octal 8 
def ine -ascii 16 
"def ine -cntr] 32 
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/* 


The c character passed to the macros below should be’declered 
85” or ‘cast to’ type ‘Byte’ or ‘unsigned char’. 


def ine 
%def ine 


-punct 
-Space 


64 
128 


gets sign extended to an integer. Thus, when c > 127 the 


-char [] subscript becomes negative! 


Such as ‘0’ do not get sign extended so they're okay. 


*/ 

"define IsAlphaNum(c) C.char[Cc2*11&C alpha| digit?) 
“define IsAlphaCc) C-char [Сс + 1]& alpha) 
"define IsAsciiCcO (char (Cc )+ 1]&_ascii) 
"define IsCntri(c) (_char [Cc2* 1J& entr 1) 


"define IsCSymCc) CC char [Cc2* 1]&C alpha| digit22| |Cc222/ 7) 


"define IsCSymFCc) ((_char[(c)+1]&_alpha)| |(c)==/_’) 


#def ine IsDigit(c) (char [Cc2* 1]& digit) 
8define IsGraph(c) (Cc»s^ 1 '&&Cc2 7" ^) 
"define IsdctDigit(c) (char [(c)+1]&_octal) 
"define IsPrint(c) ((с)›=32&&(с)‹=255) 
"define IsPunct(c) (char [Cc2* 1]&. punct) 
"define IsSpace(c) (char [(c )+1]&_space) 
8def ine IsHexDigit(c) (char (Сс )+ 1]& ћех) 
Sendif 
/* FILE: macros char .c 
Contains .cher[] used by macros in PStrLib.h */ 
8include "PStrLib.h^ 


cher .char[257] = 


( 


/* char masks allow for efficient macros */ 
0, _спіг1[_аѕсіі, cntr1|_ascii, -спіг1| ascii, 


_cntr1|_ascii|_space, cntr1|_ascii, 


_cntr1|_ascii, 


_cntr1|_ascii, 


_cntr1|_ascii, 
_сп{г1|-азс11, 


_сп{г1|-_а5с11]—врасе, _сп{г1]_азсї1|-5расе, 
-cntr1|_asciil_space, —cntr1|_ascii|_space, 


-cntr1|_asciil_space, _спіг1 | _аѕсії, 


-cntr1|_ascii, 
_cntr1|_ascii, 
-entr1| -ascii, 
-entr1| ascii’ 
-cntr1|_ascii, 
-cntr1 | ascii, 
-ascii | punct, 
_ascii|_punct, 
-Ascii|-punct, 
_ascii|_punct, 
-ascii|-punct, 


_digit|_hex|_octal|_ascii, 
_digit|_hex|_octal|_ascii, 
digit|_hex|_octal|_ascii, 
digit|_hex|_octal|_ascii, 
digit|_hex|_ascii, 


_cntr1|_ascii, 
_cntr1|_ascii, 
_cntr1|_ascii, 
_cntr1|_ascii, 
-entr1 |. ascii, 
-space | .ascii, 
ascii | punct, 
-Ascii|-punct, 
-sscii|_punct, 
_8scii|_punct, 
ascii|_punct, 


-cntr1|.ascii, 
- entr] | өсі, 
-entr1 |. ascii, 
-entr1|.ascii, 

“entri | ascii’ 
-cntr1|_ascii, 
_sscii|_punct, 
-ascii|.-punct, 
-ascii|-punct, 
-ascii|.punct, 
-ascii | рипсі, 

-di it|_hex|_octel |_ascii, 


-digit|_hex|_octal|_ascii, 
digit|_hex|_octal|_ascii, 
_digit|-hex|_octal|_ascii, 
digit |_hex|_ascii, 
_ascii|_punct, _ascii|_punct, 


_scii|_punct, -Bscii| punct, -scii| punct, 
-Ascii|.punct, .ascii|.-punct, - elpha| hex| ascii, 


“alpha -hex| ascii, 
-alpha| hex] -ascii, 
-Alpha| -hex| -ascii, 


alpha] ascii, 
-&lpha| -asci i, 
-А1рһа!| -ascii, 
-&lpha| _ascii, 
-Alpha|.ascii, 
-Alphe| -asci i, 
-ascii | punct, 
_ascii|_punct, 


_alpha|_ascii, 
_8|pha|_ascii, 
-alpha|.ascii, 
-&lpha| -ascii, 
-&lpha|.ascii, 
- plpha| ascii, 
-ascii | -рипс+, 
_85сіі | рипсі, 


-&'pha| -hex| ascii, 
-alpha| _hex|_ascii, 
-alpha| ascii, 


_alphal_ascii, 
alpha] ascii, 
-alpha| ascii, 
-alpha|.ascii, 
-alpha|.ascii, 
-Alpha|.-ascii, 
-&lpha|.sascii, 
- ascii | punct. 
-ascii|-punct, 


Туре char 
Note that immediate chars 


-cntr1|.8scii,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 0,0, 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 
90,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, 
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 

); 

/* FILE: Nua2PStr.c 
Creates а pascal string rep of а given type of 
number, returning TRUE if it fails to do so. */ 

*include "PStrL ib.h^ 


-Blpha|-ascii, -alpha|.escii, -alphal.sscii, 
-Blpha| ascii, _в1рһа | -asci i, _8scii|_punct, 
asci i |_punct, -ascii|_punct, —asciil_punct, 


Num2PStrCtype, numPtr, pStr, format, places) 


int 
void 
register char 


int format; 
int 


/* 


NOTE: When Dec2Str() fails, it sets pStr == '?'. 


type; 
*pStr; 


/* specifies Dec or Sci notation */ 
places; 


euto Decimal _Decimal_; 
euto DecForm X DecForm.; 
register int n= 1; 


/* type of var pointed at by numPtr */ 
*numPtr; /* size of *numPtr depends on type */ 
/* points to a PASCAL string */ 


/* * digits to right of Dec point */ 


The most 


common cause of failure is trying to convert a large number to 
DEC string format using а large places value. The do-while 

loop below catches such failures and fixes them by changing 
the format to SCI which virtually never fails (See the Apple 
Numer ics Manual for more details). 


*/ 
do ( 
-DecForm...style = n > 0 ? format : FLOATDECIMAL; 
DecForm_.digits = format == FLOATDECIMAL ? places + 1: 
place 


Dec2Str(_DecForm_, &_Decimal_, pstr); 
) while (р${г[1] == 27 && -n >= 0); 


5: 
"fp58kC&. DecForn.., numPtr, &_Decinal_, type + F0B2D); 


) return(pStr[1] == 29; /* Ret TRUE. if Dec2StrC) FAILED */ 


/* 


tt'include 


FILE: PStr2Nua.c 


Sets value of а given type of number based on a pascal 
string representation, returning TRUE if it fails to do so. */ 


*PStrLib.h^ 


PStr2Num(pStr, type, numPtr) 


char 


int 
void 


) 


*oStr; 


type; /* type of variable n points at */ 
*numPtr; /* generic pointer */ 


auto Decimal  decimal.; 
auto int valid, index = 1; 
/* start-scan pos. of pStr */ 


Str2Dec(pStr, &index, &decimal_, &valid); 
Грб8к(% decimal., numPtr, type + F0D2B); 
return(!valid); /% returns TRUE if failed */ 


/* points to a PASCAL string */ 


_alpha| sci i | hex, -Alpha| ascii | hex, 
-Alpha| әөсіі| һех, —alphal_ascii|_hex, 
-&lpha|-ascii|-hex, -alpha|.ascii|.-hex, 


/* FILE: PStrCat.c 
Concatenates 2-30 Pascal strings. */ 
include "PStrLib.h^ 


-&lpha| -ascii, 
-Alpha| -ascii, 
_в1рһа|-_а5с11, 
-в1рһа|-азс11, 
-&lpha| -ascii, 


-blpha|.ascii, 
-alphal.ascii, 
-а1рһа|-а5с11, 
-_а1рһа|-_а5с11, 
-_а1рһа|-_а5с11, 


_в1рһа|_азс11, 
-&lpha|.-ascii, 
-alpha| ascii, 
_а1рһа|-а5с11, 
-_а1рһа|-а5с11, 
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PStrCatCcount, dst) 


register intcount; /* 8 of strings Cincluding dst) */ 


unsigned char — *dst; /* destination pascal string */ 
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register unsigned char 
register unsigned cher 
register int 


*dstPtr, *srcPtr; 
**ergList = &dst; 
ergLen, totLen; 


if CCtotLen = *dst) < 255) ( 
if Ccount › 30) 
count = 30; /* max. # of string args 30 */ 
dstPtr » dst * totLen; 
/* dstPtr = 1 pest end of dst */ 
while (-count > Ø && totLen < 255) ( 
srcPtr = **tergList; 
arglen = srcPtr [0]; 
if CtotLen + arglen > 255) 
ergLen = 255 - totLen; 
/* max totLen = 255 */ 
totLen += ergLen; 
while (-argLen ›= Ø) /* add arg’s char to dst */ 
) **tdstPtr = *++srcPtr; 
951107 = totLen; /* sets length of dst */ 
) 


/* FILE: PStrCap.c 

Compares src to dst returning «0 less than, =0 equal, 20 
greater */ 
include "PStrLib.h^ 


PStrCmp(src, dst) 

pam unsigned char %<гс, *dst; /* Pascal strings */ 
register int slen= 
register int mien = 


*src, dlen = *dst; 
*src <= *dst ? *src : *dst; 


while C-mlen >= 0 && *++src == *++dst); 
returnCCCslen != dlen && *src == *dst) ? slen - dlen : *src 
) *dst)); 


/* FILE: PStrCopy.c 
Copys count char from pos of src to dst. */ 
"include "PStrLib.h^ 


PStrCopy(src, pos, count, dst) 
register unsigned char ‘*src, *dst; /* Pascal strings */ 
register intpos, count; 


register int max; 


“pos, 

if Ccount ? (max = *src - pos)) 
count = max; 

src += pos; 

*dst = count; 

while C-count >= 0) *++dst = ***src; 


) 


/* FILE: PStrDel.c 
Deletes count chars from pos of dst. */ 
include "PStrLib.h^ 


PStrDel(s, pos, count) 
register unsigned char *s; 
register int pos, count; 


/* Pescal string */ 


register unsigned cher +; 
register int shift; 


if (*s) { 
if (-pos * count › *s) 
count = 25 - pos; 
shift = *s - pos; 


%5 -= count; 
S += pos, 
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t = $ + count; 
while (-shift >= 0) 
¥++g = ж++{, 
) 
) 


/* FILE: PStrDrew.c 

Draws 1 to 10 Pascal strings at specified locations in the 
current GrafPort. It Offers euto-centering and New-L ine 
modes. If h == Ø then it uses the lest (current) h position. 
If v == Ø then it uses the last (current) v position. If x ‹ 0 
then s is centered inside the portRect. If y ‹ Ø then it 
offsets -y number of lines from current v pos. Otherwise, h 
end v represent the desired x and y coordinates. */ 
include "PStrLib.h^ 


PStrÜrew(count, s, h, у) 


int count;  /* number of ( s, h, v) sets to follow */ 
cher *s;  /* а pascal string to drew */ 

int h; /* horizontal position */ 

int v; /* vertical position */ 


register cher  *ergPtr = (char *)&count; 

register cher *sp; 

register Rect гр = &thePort->portRect; 

register int х, y, lineHeight = 1.5 * thePort-> txSize; 
static int о1ах = Ø, old.y = 0; 


while C-count >= 0) ( 
sp = *(cher **)(argPtr += 2); 
x = *Cint *)CargPtr += 4); 
y = *Cint *)CargPtr += 2); 
if (x »= 0) 
Old_x = x; 
else if (x I CUR)/* Auto-Center Mode? */ 
old.x = (rp»right - rp-»left - StringWidth(sp)) / 2; 
if (y >= 0) 
old.y = y; 
else if Cy != CUR)/* New-Line Mode? */ 
old_y += -y * lineHeight; 
MoveToCold.x, old_y); 
DrawStr ing(sp); 
old.x += StringWidth(sp); 
) 


/* FILE: PStrFind.c 
Finds first occurence of p in t. */ 
finclude "PStrLib.h^ 


PStrFind(p, t, pos) 
unsigned char Фр, *t; 
[UM int pos; 


/* Pescal strings */ 

/* char pos to start search */ 

/* renge of pos: 1 to 255 */ 

register unsigned char *tp = t + pos, *pp = p, *ppe=p + *p; 
register long tpe = Clong)(t + *{), /*trick ptr!*/ 


while С++рр <= ppe && t 
while (Ұрр != *tp) 

tp = t + "ров; /* tp to next pos in text */ 

pp=p + 1; /* sp to start of pattern */ 


= (unsigned cher *)tpe) ( 


++tp; /* compare next char for match */ 


return(pp > ppe ? pos : 0); 
/* Ø if Not Found, else cher position in t */ 


/* FILE: PStrFindFC.c 
Finds first occurance of c in s. */ 
include "PStrL ib.h^ 


PStrFindFC(s, с) 


register unsigned char 25; /* Pascal string */ 
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register intc; /* cher to find */ 


register int n = *s; 
register unsigned char  *sp = s; 


c &= OxFF; 


/* strip sign ext. in case caller was type cher */ 


while (*++sp != c && -n >= 0); 
return(n >= 0 ? sp -s : 0); 
) /* Result: Ø if Not Found, else cher position */ 


/* FILE: PStrFindFNS.c 
Finds first occurance in s NOT in set. */ 
"include "PStrL ib.h"^ 


PStrFindFNSCs, set) 
ге char  *s, *set;/* Pascal strings */ 


register int i**s,n 
register unsigned char ‘*setp, *sp = S; 


while (-i >= 0) ( 
*tsp; 
setp = set; 
n = *setp; 
while (-n >= 0 && ***setp != Жер); 
if (n < 0) return(sp - s); 


return(@); 
) /* Result: Ø if Not Found, else cher position */ 


/* FILE: PStrFindFS.c 
Finds first occurence in both s and set. */ 
"include "PStrLib.h^ 


PStrFindFS(s, set) 
"idus char  *s, *set;/* Pascal strings */ 


register int i = *s,n; 
register unsigned cher  *setp, *sp = 6; 


while (-i >= 0) ( 
++5р, 
setp = set; 
n = *setp; 
while C-n >= 0 && **tsetp !- *sp); 
if (n >= Ø) return(sp - s); 


returnC0); 
) /* Result: Ø if Not Found, else char position */ 


/* FILE: PStrFindLC.c 
Finds last occurance of c in s. */ 
"include “PStrLib.h” 


PStrFindLCCs, с) 
register unsigned cher  *s; /* Pascal string */ 
register intc; /* char to find */ 


register int 
register unsigned char 


n = *s; 
*tsp-s*nt*l, 


c &= OxFF; 
/* strips sign ext. in case caller was ‘char’ */ 
while (*-sp != c && -n >= 0); 
return(sp - s); 
) /*Result: Ø if Not Found, else char position */ 


/* FILE: PStrFindLS.c 
Finds last occurance in both s and set. */ 
include “PStrLib.h” 
PStrFindLSCs, set) 
unsigned char 25, *set;/* Pascal strings */ 
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( 
register int i = #5, п, 
register unsigned char  *setp, *sp=s + i; 


while (-i >= 0) ( 
setp = set; 
n = *setp; 
while (-n >= 0 && *+ttsetp != *sp); 
if (n >= 0) return(sp - s); 
7Sp; 
) 


return(9); 


) /* Result: 8 if Not Found, else char position */ 


/* FILE: PStrFixLen.c 


Sets length of pascal string s to len by either chopping 


extra chars off or by padding out with c characters. */ 


include "PStrLib.h^ 


PStrFixLen(s, len, c) 
register unsigned char *s; 
register int len; 
register int C; 


/* pascal string */ 
/* pad character */ 


register unsigned cher  *sp = s + *s; 
register int n; 


if (*s ‹ Clen & OxFF)) ( 
n = len - *s; 
while (-n >= 0) **tsp = с; 


*s = len; 


) 


/* FILE: PStrIns.c 
Inserts src at pos of dst. */ 
* include "PStrLib.h^ 


PStrInsCsrc, dst, pos) 

unsigned char *src; /* Pascal string */ 
register unsigned char ‘dst; /* Pascal string */ 
register int pos; 


register unsigned cher  *s, *d; 
register int len, shift; 


if (-pos + *src « 256) ( 
len = *src; 
*dst += len; 
shift = *dst - pos; 
s = dst + *dst; 
d = ++5 + len; 
while C-shift >= 0) 

ž-d = *-s; 


else ( 
len = 255 - pos; 
*dst = 255; 


S = dst + pos; 
while (-len >= 0) 
*++5 = *++5гс, 


/* FILE: PStrRep.c 
Replaces count chars from pos of dst with src. 
include "PStrLib.h^ 


PStrRep(dst, pos, len, src) 
register cher *dst, *src; /* pascal strings */ 
register intpos, len; 


PStrDelCdst, pos, len); 
PStrIns(src, dst, pos); 


/* тах length is 255 */ 


*/ 
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) 


/* FILE: SetFont.c 

Sets the txFont, txSize, txFace fields of the current 
GrafPort. */ 
8Sinclude "PStrLib.h^ 


SetFont(font, size, face) 
int font, size; 
ia face; 


TextFontCfont); 
TextSize(size); 
TextFaceCf ace); 


/* FILE: ShowVars.c 
Displays up to 10 sets of variable labels and values. */ 
*include “PStrLib.h” 


ShowVarsCcount, varLabel, уәгТуре, varPtr) 


int count; /* * of (verLebel,verType,verPtr) sets */ 
cher  *verLabe];  /* string label for variable */ 

int — varType; /* type of variable*/ 

cher  *verPtr; /* pointer to variable */ 

auto char **lh = &verLebel; /* Ptr ist varLabel */ 
auto int {р = &verTgpe; /* Ptr to Ist varType */ 
auto char **vh = &varPtr; /* Ptr to ist varPtr */ 
auto char *sp; 

auto Str255 5; 

auto Rect wRect; 

auto WindowPtrwp, savedPort; 

auto int y = 5; 


if Ccount > 0) ( 
if (count > 10) 
count = 10; /* max number of arg. sets */ 
GetPort(&savedPor t); 
wRect.top = 45; 
wRect.left = 72; 
wRect.bottom = count * 20 + wRect.top + 45; 
wRect.right = 440; 
wp = NewWindow(NIL, &wRect, NIL, TRUE, dBoxProc, -1L, 
FALSE, NIL); 
SetPort(wp); 
while (-count >= Ø) ( 
if (*tp == PSTR) 
Sp = *vh; 
else if (“ір == BOOL) 
Sp = **(Boolean **)vh ? “\pTRUE” : "ApFALSE*; 
else { 
sp = (char *)s; 
Lo) *vh, sp, DEC, (*tp >= CINT ? Ø : 60); 


MoveTo(30, y += 20); 

if (*lh && **1h) ( /* Length varLabel > 0? */ 
DrawStr ingC*1h); 
DrawString(“\p = *^); 


DrawString(sp); 
x 


Incr. Ptr’s 10 bytes each pass so іһеу”11 
point to the next set of arg.s on the stack. 
x/ 


lh = Cchar **)CCchar *)]h + 10); 
+= Б: 
vh = (char ®*)((char 3)vh + 10); 


) 

MoveToC30, wRect.bottom - wRect.top - 10); 
DrawString(*\pClick Mouse Button to Continue... ^); 
while (!Button());/* Wait for а mouse down event */ 
DisposeWindowC(wp); 
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SetPort(savedPort); 

) 

3 Demo draw.c <> 

7 Demo_main.c 

i MacTraps 

15 Ce 

Q 
Fig. 3 The String Demo Project 

/* FILE: Demo.main.c */ 
include “Demo .h^ 
DielogPtr Лоди; 
ControlHendle — ct1H[31; 
Rect uiRect [2]; 
int pegeNo = 1; 
Boolean 8. Boolean; 
int e. int; 
long 8.1009; 
float e. f loat; 
short double a_shor tDb1; 
double а double; 
Str255 e-Str255; 


pascal void DrawUserItem(theDlog, thel ten) 
DielogPtr theDlog; 


int 


thel tem; 


if CtheItem == 5) 

DrawPage(); /* defined in Demo_draw.c */ 
else /* (һеГ (еп must == б since only 2 userItems */ 
FillRectC&uiRect[ 1], black); /* draw line */ 


Cee 
auto int n, itemType; 
euto Rect  itemBox; 
euto Handle itemHendle; 


/* Attempt to meke modeless dialog in the heap */ 
if (dlogW = GetNewDialog(512, NIL, -1L)) ( 
/* Fetch & Stash the userItem display Rects 
& the ShowVers, Previous and Next Button 
ContolHendles. We'll need them for drawing 
the userItems and buttons. Also, install 
UserItems... */ 
for (п = 2; n <= 6; ++п) ( 
GetDItemCdlogW, n, &itemType, &itemHendle, &itemBox); 


Switch (п) ( 

case 2: /* ShowVers Button */ 
case 3: /* Previous Button */ 
case 4: /* Next Button */ 


ctIHin-2] = CControlHendle) itemHandle; 
break; 
case 5: /* Page Display - UserItem */ 
/* Separating Line — UserItem */ 
uiRect[n-5] = itemBox; 
/* Install Drew Proc for UserItems */ 
SetDItemCdlogW, n, itemType, DrewUserItem, &itemBox); 
break; 
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break; 
/* Disable the ShowVars and Previous Buttons */ 


HiliteControlCct1HLSHOW-BUT], DISABLE); HiliteControlCctlHLSHOW. BUT], CpageNo == SV. PAGE ? 
HiliteControlCctlHLPREV. BUT), DISABLE); ENABLE : DISABLE); 
else ( DisposDialog(dlogW); 
ShowVarsC1, NIL, PSTR, "ApGetNewDialogO failed...^); ) 
ExitToShel1(); 
) /* FILE: Demo_draw.c 
x/ 
Tn include  "Demo.h^ 
auto  EventRecord X eventRec; def ine X 20 
auto WindowPtr frontW; 
auto  DielogPtr theD1og; static DrawFN(sp, x, y) 
euto int itemHit; /* Draws sp and returns the pens horz.coord. */ 
auto Boolean terminated = FALSE; cher Зер; /* Pascal string (i.e. Function Name) */ 
register intx, y; 
InitGraf C&thePort); 
InitFontsC); SetFont(monaco, 9, bold); 
InitWindows(); MoveTo(x, y); 
Ini tMenus(); DrawString(sp); 
TEInitQ; x += StringWidth(sp) + 5; 
InitDialogsCNIL ); TextFace(plain); 
FlushEventsCeveryEvent, NL1); return(x); 
SetupDialog(); ) 
ShowWindowCdlogW); 
SetPor tCdlogW); DrawPage() 
InitCursor(); /* Draws the ‘Page’ UserItem (dlogItem 85) in dlogW */ 
while Clterminated) ( ( /* called by DrewUserItemC) when dlogW updated */ 
if CIGetNextEventCeveryEvent, &eventRec)) auto Str255 sl Str255, s2.Str255; 
continue; auto Rect tRect; 
if C!IsDialogEventC&eventRec)) 
continue; EraseRect(&uiRect[0]); /% Erase userItem’s Rect */ 
if C!DialogSelect(&eventRec, &theDlog, &itemHit)) switch C(pageNo) ( /* Drew the current page */ 
continue; case 1: 
if CtheDlog != dlogW) for Ca lint = Ø; e int < 2; ++а_1п{) ( 
continue; tRect.top = 30; 
switch CitemHit) ( tRect. left = 220 * a int + 90; 
case 1: /* Quit Button Hit */ tRect.bottom = 62; 
terminated = TRUE; tRect.right = tRect.left + 32; 
break ; PlotIcon(&tRect, GetIcon(512)); 
case 2: /* ShowVers Button Hit – do it! */ } 
/* Set some value to look at... */ SetFont(newYork, 18, plain); 
а_Воо1еап = TRUE; PStrDraw(1, "Ap««« MacTutor >>>”, CEN, 50); 
aint = 101; SetFont(newYork, 12, bold); 
e-long = 10101; PStrDrewC1, “\pVol.3 No. 11^, CEN, NL1); 
a-f loat = -12.21; SetFont(newYork, 18, plain); 
e-shortDb| = 654321. 123; PStrÜrewC1, "Apo Pascal String Library Demo O^, CEN, 110); 
e_double = -987654321. 123456; SetFont(newYork, 14, bold); 
PStrCopy(*\pThis is a pascal string.^, 1, ALL, a-Str255); PStrDrewC1, “\pThe following pages will explain the”, CEN, 
ShowVars(7, “\pa_Boolean”, BOOL, &a_Boolean, 150); 
“\pa_int’, CINT, &a-int, PStrürewt 1, “\p’How To’s and the ‘Results Of’ using”, CEN, 
“\pa_long”, CLONG, &a_long, NL 
“\pa-f loat”, CFLOAT, &a_float, PStrÜrew(1, “\peach function in the Pascal String Li- 
“\pa_shor tDb1”, CSHORTDBL, brary.”, CEN, NL1); 
&a_shor tDb1, break; 
“\pa_double”, CDBL, &a double, case 2: 
“Ара 54іг255”, PSTR, а_54г255); PStrDraw(1, “\pCcount, з, h, v, ...27, 
break; DrawFNC*\pPStrDraw’, X, 20), 
case 3: /* Previous Button adjust pageNo */ PStrDraw( 1, “\pcount - # of ( s, h, v) argument sets 
if (-pageNo == FIRST_PAGE) to follow.^, X, NLD; 
HiliteControlCctlHLPREV. BUT], DISABLE); PStrÜrewC1, "ips - Pascal string to draw’, X, №1); 
if (pageNo == LAST_PAGE - 1) PStrDraw(1, “\ph - Horizontal coordinate’, X, М1); 
HiliteControlCct IHINEXT- BUT], ENABLE); PStrDraw(1, “\pv - Vertical coordinate’, X, NL1); 
InvalRect(&dlogW-»portRect); /* update */ PStrDraw(1, “Үр... - 2-9 additional sets of ( s, h, 
break; у)”, X, NL1); 
case 4: /* Next Button Hit — adjust pageNo */ PStrÜrewC1, “\pPStrDraw() draws 1 to 10 Pascal strings at 
if (++pageNo == FIRST_PAGE + 1) specified locations in’, X, NL2); 
HiliteControlCctHIPREV. BUT), ENABLE); PStrDraw( 1, “\pthe current GrafPort. It Offers auto- 
if (pageNo == LAST_PAGE) centering and New-Line modes.", X, NLD; 
HiliteControlCctIHINEXT-BUT], DISABLE); PStrüÜrewC1, “\pif h == Ø then it uses the last (current) h 
InvalRect(&dlogW->portRect); /* update */ position.”, X, NL1); 
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PStrDrewC1, “\pIf v == Ø then it uses the last (current) v 
position.^, X, NL1); 
PStrDrew(1, «\рІ? x < Ø string is centered inside portRect. 
If y < 0^, X, 1); 
PStrDrewC1, *\pstring is offset -y lines from last Ccur- 
rent) v position.^, X, NL1); 
PStrDraw( 1, “\p0therwise, h and v represent the desired x 
and y coordinates.”, X, NL1); 
PStrDraw(2, "ос This was drawn by.. ^, CEN, М1], 
“\p...Calling: X, NL1); 
PStrDraw( 1, “\pPStrDraw(1, VAM GC This was drawn by... 
››\”, CEN, NLD;^ , CUR, CUR); 
break; 
case 3: 
PStrDrewC1, “\pCfont, size, face)”, DrawFNC“\pSetFont’, X, 
20), 20); 
PStrDrewC1, “\pfont - Font number”, X, NL2); 
PStrDraw( 1, “\psize Font size”, X, NL1); 
PStrDraw(1, “\pface - Font style”, X, №1); 
PStrDraw(i, “\pSetFont() sets the txFont, txSize and’, X, 
NL2); 
PStrDraw(1, “\ptxFace fields of the current GrefPort.^, X, 
2; 
PStrDraw(2, “\pCalling:”, X, NL2, “\pSetFontCmonaco, 9, 
bold);”, X*40, NL1); 
PStrDraw(2, “\pProduces Same Result As:^, X, NL2, 


“\pTextFontCmonaco);”, Х%40, NL1); 
PStrDraw(2, “\pTextSize(9);”, X*40, NL1, 


“\pTextFace(bold);”, X*40, NL1); 

break; 

case 4: 

PStrDrewC1, “\pCtype, ар; s, format, places)’, 
DrawFNC*\pNum2PStr’, X, 20), 

PStrDraw( 1, *Aptype = ‘CINT, CLONG, CCOMP, CFLOAT, 
CSHORTDBL, CDBL^, X, М2); 

PStrDraw(1, “\pnumPtr - Address of a given type of 
number”, X, NL1); 

PStrDrewC1, “\ps - Pascal string to recieve the 
string representation”, X, NL1); 

PStrDrewC1, “\pformat - DEC or SCI Cdecimal or 
scientific notation)”, X, NL1); 

PStrDrewC1, “\pplaces - Number of decimal places 
desired in representation’, X, NL1); 

PStrDrewC1, “\pNum2PStr() creates а pascal string 


representation of a given’, X, М2); 

PStrDrewC1, “\ptype of number in either decimal or 
scientific notation.^, X, М1); 

a_double = -987654321.987654321; 

PStrDrewC1, “\pGiven: a double == - 
987654321.987654321^, X, М2); 

PStrDraw(1, “\pCalling: 
s1.Str255, DEC, 9);”, X, М1); 

Num2PStrCCDBL, &a double, si_Str255, DEC, 9); 

PStrDraw(3, “\pResults In: $1_Str255 == \*\\р*, X, 
NL1, s1.Str255, CUR, CUR, “\p\*”, CUR, CUR); 

Num2PStr(CDBL, &e_double, s1_Str255, SCI, 17); 


Num2PStrCCDBL, &a_double, 


PStrDrewC1, “\pCalling: Num2PStrCCDBL, Фа. double, 
s1.Str255, SCI, 17);”, X, NL1); 

PStrDraw(3, “\pResults In: $1 Str255 == \“\\p’, X 
NL1, 91507255, CUR, CUR, "\p\””, CUR, CUR); 

break; 

case 5: 

PStrDrewC1, “\pCs, type, numPtr2^, DrawFNC%\pPStr2Num’, 
X, 20), 20); 

PStrDrewC1, “\ps - Pascal string representation 
of a number”, X, NL2); 

PStrDraw(1, “\ptype - CINT, CLONG, CCOMP, CFLOAT, 
CSHORTDBL, CDBL^, X, NL1); 

PStrDraw(1, “\pnumPtr - Address of а given type of 
number”, X, NL1); 

PStrDraw( 1, “\pPStr2Num() sets а given type of number 
equal’, X, М2); 

"PStrDraw1, “\pto the value represented in the pascal 


string s.^, X, ND; 
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PStrCopy(“\p- 123456789 .987654321^, 1, ALL, si. Str255); 


PStrDraw(1, “\pGiven: $1_Str255 == \*\\p- 
123456789 .987654321\**, X, NL2); 

PStrDrewC1, “\pCalling: PStr2Num(s 1_Str255, CDBL, 
&a_double);”, X, NL1); 


PStr2Num(s1_Str255, CDBL, &a double); 
Num2PStrCCDBL, &a double, s2.Str255, DEC, 9); 


PStrDraw(2, “\pResults In: — &-double == *, X, NL1, 
82 Str255, CUR, CUR); 
break; 
case 6: 
PStrDrewC1, “\p(src, pos, count, dst)’, 


DrawFNC* pPStrCopy" , X, 20), 205; 


PStrDraw( 1, "\psre - Source pascal string’, X, NL2); 

PStrDraw( 1, “\ppos - (Character position in src to 
start copying”, X, NL1); 

PStrDrewC1, “\pcount - Number of characters to сору”, 
X, NLD; 

PStrDrewC1, “\pdst - Destination pascal string’, X, 
М1); 

PStrDrewC1, “\pPStrCopy() copies count characters from’, 
X, NL2); 

PStrDraw( 1, “\pcharacter position pos of src to dst.^, 
X, М1); 


PStrCopy("\pThis is a pascal string’, 1, ALL, 
$1_Str255); 


PStrDrewC1, “\pGiven: $1_Str255 == VAWpThis is a 
pascal stringV/^, X, М2); 

PStrDraw(1, “\pCalling: PStrCopy(s1_Str255, 1, ALL, 
52 Str255); ^, X, NL1); 

PStrCopy(s1_Str255, 1, ALL, s2_Str255); 

PStrDraw(3, “\pResults In: s2.Str255 == \“\\p’, 
NL1, s2.Str255, CUR, CUR, “\p\’”, CUR, CUR); 

PStrDraw(1, “\pCalling: PStrCopy(s2_Str255, 11, 6, 
81.5іг255);%, X, NL1); 

PStrCopy(s2_Str255, 11, 6, 61.54г255); 

PStrDraw(3, “\pResults In: si. Str255 == VAWp*, X 
NL1, s1_Str255, CUR, CUR, “\p\’”, CUR, CUR); 

break ; 

case 7: 

PStrDrewC1, “\pCcount, dst, ...2”, DrawFNC%\pPStrCat’, 
X, 200, 20); 

PStrDraw(1, “\pcount - Number of string arg. present 
INCLUDING dst”, X, М2); 

PStrDraw( 1, “\pdst - Destination pascal string’, X, 

М 1); 


) 

PStrDrewC1, "Mp... = 
arguments”, X, NL1); 

PStrDraw( 1, “\pPStrCatC) concatenates 1-29 additional 


1-29 additional pascal string 


pascal strings onto dst.^, X, NL2); 
PStrCopy(“\pThanks for’, 1, ALL, si_Str255); 
PStrDraw( 1, “\pGiven: 81 5іг255 == \*\\рТһапкѕ 
forV^^, X, М2); 
PStrÜrewC1, “\pCalling: PStrCat(3, s1.Str255, Vp 
the hot\”, \“\\ptip!\");7, X, М1); 
PStrCat(3, s1_Str255, “Үр the hot’, “Үр ир; 
PStrDraw(3, “\pResults In: $1_Str255 = = \"\\p”, X, №1, 
81.5іг255, CUR, CUR, “\p\’”, CUR, CUR); 
break; 
case 8: 
PStrÜrewC1, “\p(src, dst, pos)”, DrewFNC^MpPStrIns^, X, 
20), 20); 
PStrDrewC1, “\psrc - Pascal string to insert into 
dst”, X, М2); 
PStrDraw( 1, “\pdst - Destination pascal string 
(recieves insertion)”, X, NL1); 
PStrDrewC1, “\ppos - Character position of insertion 
in dst”, X, М1); 
PStrDraw( 1, “\pPStriIns() inserts src at pos into dst.’, 
X, NL2); 
PStrCopyC ^ WThat is nice.^, 1, ALL, $1_Str255); 
PStrDraw(1, “\pGiven: $1Str255 == \“\\pThat is 
nice. V^, X, М2); 
PStrDrewC1, “\pCalling: PStrIns(VANpvery 57, 
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s1.Str255, 9);7, X, М1); 
PStrInsC^Mpvery *, si_Str255, 9); 
PStrDraw(3, “\pResults In:  si-Str255 
NL1, 51.5іг255, CUR, CUR, «\р\^*, CUR, CUR); 


== \"\\p", X 


break; 
case 9: 
PStrDrewC1, “\pCs, pos, count)”, DrawFNC“\pPStrDel’, X, 
20), 20); 
PStrDrewC1, “\ps - Pescal string recieving 
deletion’, X, NL2); 
PStrDrewC1, “\ppos - Character position to start 


deleting”, X, NL1); 

PStrDraw( 1, “\pcount - Number of characters to be 
deleted”, X, NL1); 

PStrDraw( 1, “\pPStrDel() deletes count characters 
starting at pos from s.^, X, NL2); 

PStrCopy(*\pHe has not finished.^, 1, ALL, si_Str255); 

PStrDrewC1, “\pGiven: $1_Str255 == \“\\pHe has 
not finished.\“%, X, М2); 

PStrDrewC1, “\pCalling: PStrDel(s1 Str255, B, 4);”, 
X, М1), 

Р5ігбе1(61. 5іг255, 8, 45;; 


PStrDrew(3, “\pResults In: si. Str255 == \"\\p’, X, 
NL1, $1_Str255, CUR, CUR, ”\p\””, CUR, CUR); 
break; 
сазе 18: 
PStrDrewC1, “\pCsrc, pos, count, dst)’, 
DrawFNC*\pPStrRep’, X, 20), 20); 
PStrDraw(1, “\pdst - Pascal string recieving 
replacement”, X, NL2); 
PStrDrawC1, “\ppos - Character position to start 
replacing’, X, NL1); 
PStrDrewC1, “\pcount - Number of characters to 
replace’, X, NL1); 
PStrDrewC1, “\рѕгс - Pascal string replacement’, X, 
М1); 


PStrDraw(1, “\pPStrRep() replaces count characters”, X, 
2: 


7 
PStrDrewC1, “\pstarting at pos in dst with өгс.”, X, М1); 
PStrCopy(“\pJane гап home.^, 1, ALL, 81. Str255); 
PStrDrewC1, “\pGiven: 61.5іг255 == \“\\pJane ran 
home. \””, X, М2); 
PStrÜrewC1, “\pCalling: 
VAMpywalkedV 2; ^, X, NL1); 
PStrRep(s1_Str255, 6, 3, “\pwalked”); 
PStrDrew(3, “\pResults In:  s1.Str255 == 
s1.Str255, CUR, CUR, “\р\””, CUR, CUR); 
break; 
case 11: 
PStrDrewC1, “\pCs, len, с)”, DrewFNC^MpPStrF ixLen^, X, 
20), 20); 
PStrDraw(1, “\ps Pascal string”, X, NL2); 
PStrDraw(1, “\plen - Desired length’, X, М1); 
PStrDraw(1, "рс  - Character used to pad to greater 
length^, X, М1); 
PStrDrewC1, “\pPStrFixLen() gaurantees that the length 
of s to^, X, NL2); 
PStrDrewC1, “\pbe equal to len by chopping extra 
characters off^, X, NL1); 
PStrDrew( 1, “\por by padding-out with as many c’s as 
neccessary.”, X, NL1); 
PStrCopy¢*\pyohn Doe”, 1, ALL, $1_Str255); 
PStrDrewC1, “\pGiven: $1_Str255 = 
DoeV^^, X, М2); 
PStrDraw(1, “\pCalling: 
');*, X, М1); 
PStrF ixLenCs1 Str255, 10, * “); 
PStrDraw(3, “\pResults In:  581-5{г255 == VAMp^, X 
NL1, s1Str255, CUR, CUR, “\р\””, CUR, CUR); 
PStrDraw(1, “\pCalling: PStrF ixLen(s1_Str255, 4, 
9; X, М1); 
PStrFixLenCs1.Str255, 4, “ 9; 
PStrDrew(3, “Без із In: $1_Str255 == 
NL1, s1.5tr255, CUR, CUR, “\p\7%, CUR, CUR); 


PStrRep(s1_Str255, 6, 3, 


\2\\р^, X, NLI, 


= \“\\puohn 
PStrFixLen(s1_Str255, 10, ' 


үле, X, 
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break; 
case 12: 
PStrDraw( 1, “\pCp, t, pos)”, DrawFNC*\pPStrFind’, X, 
20), 20); 
PStrDrewC1, “\pp 
to find.^, X, М2), 


- Pescal string containing pattern 


PStrDrew(1, “\pt - Pascal string of text to 
search.^, X, NL1); 

PStrDrawC1, “\ppos - Character position in t to start 
searching.”, X, NLD; 


PStrÜrewC1, *VpPStrF indC) finds the first occurance of p 
in t.”, X, М2); 

‘PStrDraw( 1, “\pIt returns the char .position found else 
zero.^, X, NL1); 

"PStrCopuC^WpI em that I em.^, 1, ALL, si_Str255); 


PStrDraw(1, “\pGiven: 81-5{г255 == \“\\pI am that 
I en. V^, X, NL2); 
PStrÜrewC1, “\pCalling: aint = PStrFind( “Арат”, 


81.5іг255, 1);*, X, М1); 
aint = PStrFind(^Mpen^, si. Str255, 1); 
Num2PStrCCINT, &a_int, 52 5%г255, DEC, 0); 
PStrDraw(2, “\pResults In: aint == “©, X, МІ, 
52 Str255, CUR, CUR); 
PStrDrewC1, “\pCalling: 
$1_Str255, 5);”, ; 
aint = PStrFind(*\pam’, si. Str255, 5); 
Num2PStrCCINT, ке_іпі, s2_Str255, DEC, 0); 
PStrDraw(2, “\pResults In: а_ int ==", X, NLI, 
s2.Str255, CUR, CUR); 
break; 
case 13: 
PStrDrewC1, “\p(s, с)”, DrawFNC*\pPStrFindFC’, X, 20), 20); 
PStrDraw(1, “\ps - Pascal string to search”, X, М2); 
PStrDrewC1, “\pc - Character to find", X, NL1); 
PStrDrewC1, “\pPStrFindFCC) finds the first occurance of 
c in s.^, X, М2); 

PStrDraw(1, “\pIt returns the char.position found else 
zero.”, X, NL1); 

PStrCopy(*\pabcdefg”, 1, ALL, s1_Str255); 


a_int = PStrFind( “Арат”, 


PStrDrewC1, *\pGiven: $1_Str255 == 
\“\\pabcdefg\*", X, М2); 
PStrDrewC1, “\pCalling: aint = 


PStrF indFC(s1_Str255, ‘e’);”%, X, NL1); 
aint = PStrFindFCCs1. Str255, ʻe’); 
Num2PStrCCINT, &a_int, s1_Str255, DEC, 0); 
PStrDrew(2, “\pResults In: a int == “, X, №1, 
$1_Str255, CUR, CUR); 
break; 
case 14: 
PStrÜrewC1, “\p(s, с)”, DrawFNC*\pPStrFindLC’, X, 20), 20); 
PStrDrewC(1, “\ps - Pascal string to search”, X, М2); 
PStrÜrewC1, "pc - Character to find”, X, М1); 
PStrDraw( 1, “\pPStrFindFCC) finds the last occurance of c 
in s.^, X, М2); 
PStrOraw( 1, топ returns the cher.position found else 
zero.^, X, NL D; 


PStrCopy(*\pabcde abcde”, 1, ALL, s1_Str255); 


PStrDrewC1, “\pGiven: 81 5іг255 == \”\\pabcde 
ebcdeV^^, X, М2); 
PStrÜrewC1, “\pCalling: aint = PStrFindLCCs1.Str255, 


'b'5;*, X, NL1); 

e_int = PStrFindLC(s1_Str255, ‘b’); 

Num2PStrCCINT, фа. іпі, 51.5%г255, DEC, 0); 

PStrürew(2, “\pResults In: әгіпі == *, X, №1, s1_Str255, 
CUR, CUR); 

break; 

case 15: 

PStrDrewC1, "ApCs, set)”, DrawFNC“\pPStrFindFS”, X, 20), 
20); 

PStrÜrew(1, “\ps - Pascal string to search”, X, М2); 

PStrDraw(1, “\pset - Pascal string considered as a set of 
characters’, X, NL1); 

PStrDrewC1, “\pPStrFindFSC) finds the first occurance in 
both s and set.^, X, NL2); 


169 


PStrDraw(1, “\pIt returns the cher.position found else 
zero.^, X, М1); 

PStrCopy(^MpThis works greaet!^, 1, ALL, s1_Str255); 

PStrDraw(1, *\pGiven: $1Str255 == \“\\pThis works 
great!\“", X, М2); 

PStrDraw(1, “\pCalling: а_іпі = PStrFindFSCs1.Str255, 
VANpebc V; *, X, NL1); 

e.int = PStrFindFSC(s1 Str255, “\pabc”); 

Num2PStrCCINT, &a sint, 51.5іг255, DEC, 0); 

PStrDrew(2, “\pResults In: a_int == “©, X, NL1, si-Str255, 
CUR, CUR); 

break; 

case 16: 

PStrDrewC1, “\p(s, set)”, DrawFNC*\pPStrFindLS’, X, 20), 
20); 

PStrDraw(1, “\ps - Pascal string to search", X, NL2); 

PStrDraw(1, “\pset - Pascal string considered as a set of 
characters’, X, NL 1); 

PStrDraw( 1, *\pPStrF ind SC) finds the last occurance in 
both s and set.” X, NL2); 

PStrDraw(1, “ой returns the char.position found else 
zero.^, X, NL15; 

PStrCopyC^MpPeace, Peace!^, 1, ALL, si. Str255)5; 


PStrDrewC1, “\pGiven: $1_Str255 == \*\\рРеасе, 
Peace! \””, X, М2); 
PStrDraw(1, “\pCalling: aint = PStrFindLSCs1 Str255, 


\*\\pabc\");7, X, NL1); 

aint = PStrFindLSCs1.Str255, “\pabc”); 

Num2PStrCCINT, &a_int, s1.Str255, DEC, 0); 

PStrDraw(2, “\pResults In: a int ==", X, М1, si_Str255, 
CUR, CUR); 

break; 

case 17: 

PStrDraw(1, “\p(s, set)”, DrawFNC“\pPStrFindFNS’, X, 20), 
20); 

PStrDrewC1, “\ps - Pascal string to search’, X, М2); 

PStrDrew(1, “\pset - Pascal string considered as a set of 
characters”, X, NL 15; 

PStrDraw(1, *\pPStrF indFNSC) finds the first occurance NOT 
in both s and ‘set. ^, X, NL2); 

PStrDraw(1, “\pIt returns the char .position found else 
zero.^, X, NL1); 

PStrCopy(“\pS.0.S., $.0.S%, 1, ALL, si. Str255)5; 

PStrDrewC1, “\pGiven: si.Str255 == \*\\pS.0.S., 
$.0.9V^^, X, М2); 

PStrDrewC1, “\pCalling: а_іпі = PStrF indFNS(s1_Str255, 
VANpS.0V/5;^, X, М1); 

aint = PStrFindFNSCs1.Str255, “\р5.0*); 

Num2PStr(CINT, &a_int, s1_Str255, DEC, 0); 

PStrDraw(2, “\pResults In: aint zz 4 X, NL1, si. Str255, 
CUR, CUR); 

break; 

case 18: 

PStrDraw(1, “\pCsi, 522”, DrewFNC^MpPStrCmp^, 

PStrDrewC1, “\р51 - Pascal string’, X, М2); 

PStrDrewC1, “\ps2 - Pascal string’, X, NL D; 

PStrDrewC1, “\pPStrCmp() compares s1 to 52.”, X, М2); 

PStrDraw(1, “\pResult: «8 less than; ==0 equal; >Ø 
greater than’, X, NL1); 

PStrDrewC1, “\pCalling: a_int = PStrCmpC\*\\pABCD\’, 
VANpABCEV; ^, X, М2); 

aint = PStrCmpC*\pABCD’, “\pABCE”); 

Num2PStrCCINT, &e_int, s1.Str255, DEC, 0); 

PStrDrew(2, “\pResults In: а_іпі == *, X, М1, s1_Str255, 
CUR, CUR); 

PStrDraw(1, “\pCalling: 
\"\\pABCD\");7, X, NL1); 

aint = PStrCmp(“\pABCD’, “ҮрАВС0”); 

Num2PStrCCINT, &@_int, 51.5іг255, DEC, 0); 

PStrDrew(2, “\pResults In: а_іпі == *, X, №1, $1_Str255, 
CUR, CUR); 

PStrÜrewC1, “\pCalling: 
VANpABCDEV2; 5, X, М1); 

aint = PStrCnpC^MpABCDF ^, “\pABCDE”); 


X, 20), 205; 


aint = PStrCnpC VA NpABCD M, 


aint = PStrCnpC VA NpABCDF \’, 
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Num2PStrCCINT, &a int, si. Str255, DEC, 0); 
PStrDraw(2, “\pResults In: а_іпі == *, X, МІ, $1_Str255, 
CUR, CUR); 
PStrDrewC1, “\рСа11іго: aint = PStrCmpC\"\\pABC\’, 
VANpABCDVA2; ^, X, NL1); 
aint = PStrOmpC^MpPStr 1^, “\pPStr 127); 
Num2PStrCCINT, &e_int, s1_Str255, DEC, 0); 
PStrDraw(2, “\pResults In: a int ша” X, №1, s1_Str255, 
CUR, CUR); 
break; 
case 19: 
PStrDrewC1, “\pCcount, varLabel, varType, varPtr, ...)”, 
DrawFNC“\pShowVars’, 8, 15), 15); 


PStrDraw(1, “\pcount - 8 of ( verLebel, varType, 
varPtr ) arg. sets to follow’, 8, NL1); 
PStrDraw(1, “\pvarLabel - Pascal string used as 


variable’s label”, 8, NL1); 
PStrDraw(1, “\pvarType - Туре of variable”, 8, М1); 
PStrDraw(1, “\pvarPtr — - Variable’s address’, 8, 
NL 1); 
PStrDrewC1, “\p... - 1-9 additional sets of ( 
varLabel, varType, verPtr )”, 8, NL1); 
PStrDraw( 1, “\pShowVars() displays the label & value of 
1-18 variables. It’s а”, 8, М1); 
PStrDraw(1, “\pgreat run-time debugging tool! Here's an 
example calling sequence:”, 8, NL1); 
Tex tFace(bold); 
PStrDrewC1, “\p<<< Click ShowVars Button To See Result 
›”‚ CEN, NL1); 
TextFace(plain); 
PStrDrewC1, “\pShowVars(7, \"\\pa_Boolean\’, BOOL, 
&a_Boolean, ^, 8, М1); 
PStrDraw( 1, *\р 
М1); 
PStrDrewC1, "ip 
8, NL1); 
PStrDrewC1, “\p 
&a-floet,^, 8, NL1); 
PStrDrewC1, “\p 
&a-shortDb1,^, 8, NL1); 
PStrDrewC1, "Ap 
&e_double,”, 8, NL1); 
PStrDrewC1, “Үр 
81.5іг255);%, 8, М1); 
break; 
case 28: 
SetFont(monaco, 9, plain); 
PStrÜrewC1, “\pThe Following macros are defined in 
PStrLib.h: IsAlphaNum(c),”, X, 20); 
PStrDraw( 1, "\pIsAlphatc), ІѕАѕсііСс), IsCntrlCc2, 
IsCSym(c), IsCSynF (c), ” X, М1); 
PStrDraw( 1, *\pIsDigit(c), IsGraph(c), IsOctDigitCc), 
IsPr intCc2, IsPunct(c), f X 2: 
PStrDraw( 1, "Ap IsSpace(c) IsHexDigit(c). 
character c for their’, X, NL1); 
PStrDraw( 1, "\prespective conditions returning Ø if FALSE 
else 20 TRUE. WARNING:^, X, NL1); 
PStrDrewC1, “\pDon’t use c’s delcared as type char (see 
PStrLib.h for ехр1апа{іоп)!*, X, М1); 
a. int = IsAlphaC‘a’); 
Num2PStrCCINT, фа _іпі, si_Str255, DEC, 0); 
PStrDraw(3, “\pExecuting: a- int = IsAlphat а”); ME S 
NL2,“\pResults In: a _int == *, X, М1, si. Str255, CUR, CUR); 
e_int = IsAlphaC'1^)2; 
Num2PStrCCINT, &a_int, s1_Str255, DEC, 0); 
PStrDraw(3, “\pExecuting: ‚ e-int = IsAlpha('1^); 172%; 
NL 1,”\pResults In: а_іпі == *, X, М1, $1_Str255, CUR, CUR); 
e.int = IsDigit(’a’); 
Num2PStr(CINT, &a int, s1_Str255, DEC, 0); 
PStrDraw(3, “\pExecuting: a- int = IsDigit( ‘a’ э”, К, 
NL1,“\pResults In: a_int == *, X, NL1, s1_Str255, CUR, CUR); 
а_іпі = IsDigitC'1^5; 
Num2PStrCCINT, &a_int, si_Str255, DEC, 0); 
PStrDraw(3, “\pExecuting: a_int = IsDigitC'1/5;^, X, 


\“\\pa_int\”, CINT, &e_int,”, 8, 
\“\\pa_long\”, CLONG, &a_long, ", 
\"\\pa_float\’, CFLOAT, 
\“\\pa_shor tDb1\", CSHORTDBL, 
\“\\pa_double\”, CDBL, 
\“\\pa_Str255\", РТВ, 


They 811 test 
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NL1,“\pResults In: а_іпі == *, X, М1, si. Str255, CUR, CUR); 54 40 323 472 


break; Invisible NoGoAway 
16 
/* Drew pageNo page in userItem's display rect */ 0 
Num2PStrCCINT, &pageNo, 52. Str255, DEC, 0); 512 
s1.Str255[0] = 0; 
PStrCat(3, s1.Str255, “\pPage *, s2_Str255); type DITL 
TextFontCnewYork); ‚512 
Тех{$1те( 10); 
TextFaceCbold); 
PStrDrewC1, s1.Str255, CEN, 230); BtnItem Enabled 
) 245 16 263 104 
Quit 
/* FILE: рево.ћ 
*/ BtnItem Enabled 
include «DialogMgr.h» 245 120 263 208 
include «ControlMgr.h? ShowVars 
include <EventMgr .h> 
include <PStrLib.h» BtnItem Enabled 
245 224 263 312 
idef ine SHOW. BUT 0 Previous 
"def ine PREV_BUT 1 
"def ine NEXT. BUT 2 BtnItem Enabled 
"def ine FIRST_PAGE 1 245 328 263 416 
def ine SV. PAGE 19 Next 
"idef ine LAST.PAGE 20 
"def ine ENABLE 0 UserItem Disabled 
def ine DISABLE 255 0 0 235 432 
extern DielogPtr  dlogW; 
extern ControlHandle ctlH(3]; UserItem Disabled 
extern Rect uiRect 2]; 236 0 238 432 
extern int pegeNo; 
extern Boolean e. Booleen; 
extern int aint; type ICON = GNRL 
extern long a long; ‚512 
extern floet a.f loat; .H 
extern short double  a.shortDb]; eTFFTFFC ØFFE8ØF8 OTFFT7F30 OS3FFFFEO 
extern double e- double; Q0FFFFDO 0 11РЕЕС8 0207ҒҒ48 0201ҒЕ5С 
extern Str255 а.54г255; 02307048 0278 1854 02640048 02000054 
02000048 02806254 02ВЕҒАТ8 02ҒҒҒЕ5Т 
* FILE: фево.рго).В Q2TEFC57 02107055 02000040 O1FFFF80 
* g1FFFF80 06000060 08С66610 10000008 
Demo .proj.rsrc 26318CC4 20000004 3FFFFFFC 00000000 
???????? 09 188382 ААА 12925 8BA12954 8A993924 
OTFFFFFC 
type DLOG 
‚512 
C Language 
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Advanced Mac 'ing 


How to Write a Printer Driver 


Writing a Simple Macintosh Printer Driver 
Part 1: Overview 


A Macintosh Printer Resource File is a file containing re- 
sources to emulate QuickDraw drawing commands on a printer 
or other remote device. This article describes how to write a 
Printer Resource File which implements text-drawing com- 
mands only on serial dot matrix and daisy wheel printers. The 
printer file is installed using the Chooser in the same manner as 
one would install the ImageWriter or LaserWriter file. The 
printers which are serviced by this printer driver are assumed to 
be capable of printing in only one font, which is mono-spaced. 
An ability is included in the printer driver to change serial port 
settings and printer control strings, so that a large number of 
different types of printers may be used with one driver. In 
addition, it is Shown where more advanced drawing commands 
(graphics and proportional fonts) would fit into the structure of 
the Printer Resource File. ThisPrinter ResourceFile was written, 
from scratch, by the author in two weeks. I am not a professional 
programmer, or even a registered Macintosh developer. I feel 
that the dearth of Printer Drivers for the Macintosh is due more 
to apparent, rather than real, difficulties in writing them. 

I wrote my Printer Resource, which I christened Daisy, using 
LightspeedC for the code resources and RMaker for the data 
resources in the file. The table below summarizes all the 
resources in my Printer Resource. Most of these follow the 
standard types and IDs used by Apple, but some are particular to 
my implementation. 

Printer File Resources and Function (Public) 


Type 10 Function 
"DRVR^ -8192 Device driver: performs low-level 
printer calls and maintains storage 
‘PREC’ -8192 Driver's private storage 
‘PREC’ Default print record 
‘PREC ’ 1 Copy of last used print record 
'PDEF ’ 0 Draft mode printing routine 
'PDEF ’ 1 Spooling routine (not used) 
^PDEF ^ 2&3 Printer specific printing code (пої used) 
'PDEF ^ 4 Code for handling printing dialogs 
'PDEF ’ 5 Spool file printing routine (поі used) 
‘PACK’ -4096 Chooser interface code, used for 
device configuration 
‘STR * -8191 Default spool file name 
‘STR ^ -4096 Type name for AppleTalk devices (not used) 
ӨТЕ” -4093 Title for Chooser left button (not used) 
ӨТЕ” -4092 Title for Chooser right button 
‘STR ° -4091 Chooser list label 
‘STR * -4090 Chooser reserved string (not used) 
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Fig. 1 Our Printer Driver is Chooser Compatible! 


‘DLOG’ -8192 Paper Style dialog 

‘DITL’ -8192 Paper Style dialog template 

‘DLOG’ -8191 Paper Job dialog 

‘DITL’ -8191 Paper Job dialog template 
(Private) 

(00067 -4080 PACK resource installation dialog 

'DITL^ -4080 Installation dialog template 

'Stng^  -8192 Private type, printer settings 

‘STR’ -4080 Printer control string list 

‘BNDL’ 128 For the file's icon 

'DesY ’ 9 File creator, resource is а ‘STR ' 

‘FREF’ 128 Рог the file's icon 

"1087 128 Icon and mask 

'DLOG^ -8103 Sheet feed dialog 

'DITL^ -8193 Sheet feed dialog template 


The Printer Resource file contains a fairly large number of 
resources, but each one has a well defined function. All of the 
"public" resources have type names and ID numbers rigidly 
defined by Apple, and also specific formats. The private re- 
sources should have ID numbers of “owned” resources, owned 
by either the driver, one of the ‘PREC’ resources, or the ‘PACK’ 
resource so as not to conflict with any application resources. The 
file must have a ‘BNDL’, ‘FREF’, ‘ICN#’, and creator resource 
in order to appear in the Chooser display. This printer file uses 
the Chooser interface code, ‘PACK’ -4096, so it therefore needs 
to be installed with the Chooser, and not Choose Printer. 

This printer resource file is of type ‘PRER’, or ‘non-serial 
printer’, so that it can use the Chooser interface to query the user 
for application-independent installation parameters. These in- 
clude the baud rate, what kind of flow control to use, and some 
printer control strings. If your printer resource does not need to 
use the Chooser interface, then you can make it of type ‘PRES’, 
or serial printer, and the Chooser will take care of all details of 
installation. If you do it this way, then the Chooser will put the 
user's choice of serial port in parameter RAM, so that your 
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printer driver can find it later. 

The Printer Resource File contains a number of resources 
containing pure 68000 (or 68020) machine code. The ‘DRVR’ 
handles low-level Printing Manager calls, while the *PDEF' 
resources handle high level printing. It is possible to define up 
to four different kinds of high level printing, but it is only 
necessary to provide one. The ‘PACK’ resource containsa single 
routine to handle the printer installation process. I wrote all of my 
code resources using LightspeedC, and used some InLine assem- 
bly to format the headers of the resources where required. There 
are some requirements which must be met by the development 
system used. The development system must be capable of 
producing stand alone code resources, and must allow you to 
specify the format of the code resource header. The development 
system must also be capable of producing functions that are 
called according to the Pascal conventions in Inside Macintosh. 
It appears then that most commonly available C and Pascal 
development systems are capable of producing working printer 
files, with perhaps a few dozen lines of assembler “glue” to make 
things fit together. 

Of the non-code resources, most are standard, except for the 
"Sung" type and the ‘PREC’ type. The ‘Stng’ type is just an array 
of integers I use to store configuration values, and is unique to my 
implementation. The ‘PREC’ type (0 and 1) is a disk copy of the 
Printing Record data structure, which the printing code uses to 
keep track of paper size and other parameters associated with 
each printing "job". The printing record will be discussed in 
detail when I treat the style and job dialog code. The ‘PREC’ - 
8192 is merely a disk copy of whatever storage is needed by the 
driver and printing code. A good way to initialize variables used 
by the printer file is to keep their default values in a data structure 
in this resource. When LightspeedC creates a device driver, it 
uses a resource of type 'DATA' to do this, and creates initializa- 
tion code to load it in when the driver is opened. Since the 
Chooser does not install the ‘DATA’ resource for me, I keep it in 
the printer resource file, and give it a type reserved for printer 
driver storage. When the driver is opened, I open the printer 
resource file, and load my storage resource before doing anything 
else. 

When the printer is installed by the Chooser, the driver is 
added to the system resource file, and the ID is changed from - 
8192 to 2. The name is also changed from “.ХРгіпі” to **.Print". 
The structure of the printer resource file is admittedly fairly 
complicated. Taken a piece at a time, however, it is not a 
particularly difficult task to write one. 

| Part 2: The driver 

The Printer Resource File code is written as a series of 
separate overlays, each of which has a specific function and a 
rigidly defined format. We will start with the driver. The driver 
has the same structure as any Macintosh device driver or desk 

accessory, and responds to Open, Close, Control, and Status 
calls. It does not appear to respond to Prime (read/write) calls. 
The driver's private storage was originally contained, as a 
resource, in both the Printer Resource File and the System 
Resource File as a resource of type ‘PREC’ with the same 
resource ID as the driver. Apple appears to have discontinued 
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this practice, but we will use it to store data structures used by 
various parts of the printing code. The driver shown here is 
written using the LightspeedC compiler, device driver option. 
When global variables are defined in a LightspeedC device 
driver project, they are stored in a resource of type ‘DATA’ and 
accessed via offsets from register A4. This is changed to type 
‘PREC’, and code is provided to load this resource in at open 
time. The driver's private storage is found in a Handle stored in 
the driver's Device Control Entry, and is referenced through the 
dereferenced Handle. 

The initialization code I have written for the device driver 
opens the Printer Resource File, loads the resource containing the 
driver's private storage, and stores the Handle to it in the driver's 
DCE. Ihave to provide code for opening the Printer Resource 
File, because it is possible to open the printer driver without the 
Printer Resource File being open at the time. The standard means 
of opening the printer driver is to call PrOpen, which opens the 
Printer Resource File. Assume the worst, however, and give the 
driver a means of opening the resource file. I use SysEnvirons to 
get the RefNum of the folder with the system resource file in it, 
and OpenRFPerm to open the printer resouce file. If the machine 
is older than 128k ROMS, I use OpenResFile, and hope that this 
routine looks on the volume containing the system (it probably 
does). I have not done verification tests on ANY parts of my 
printer driver for 64k ROMs or Mac XLs. Sorry. 

The driver's private storage is defined in a header file, so that 
it can be shared between the driver and other printing code 
overlays. Using conditional compilation, the same identifiers are 
used for static variables in the driver code, and data structure 
members in the other overlays. 

The functions the driver open routine is expected to perform 
are as follows: It initializes a “permanent” storage area used by 
the printing code. It opens a channel to the serial driver used for 
printing. In my printer driver, it obtains settings to be used during 
printing from the printer resource file. The driver responds to 
several device manager control calls which are expected to 
perform useful printer functions. My driver loads a string list 
from the Printer Resource File which contains strings to perform 
these functions, so they can be changed without recompiling the 
code. In addition to hardware-oriented device control calls, the 
driver answers one control call and one status call from the Font 
Manager. These are for the purpose of determining which fonts 
and spacings the printer is capable of. Most applications appear 
to ignore this information, and attempt to print what is shown on 
the screen. We provide the font information anyway, since it 
can't hurt. 

LightspeedC provides a rather different programming shell 
for device drivers and desk accessories from that which is used 
by other development systems. The programmer writes one 
function, main(), which is called with the same parameters that 
are used to call the Open, Control, Status, Prime, and Close 
routines of the driver. A third parameter, an integer, indicates to 
main() which of the five driver routines was, in fact, intended. A 
switch statement in my driver code takes the place of the five 
device driver routines which you would have to write if using 
another development system. Note that this is certainly non- 
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standard! 

The first driver routine to be called is the open routine. This 
may be called several times during the course of an application 
session. We are called here, and everywhere, with three parame- 
ters: a parameter block, a device control entry pointer, and 
(particular to LightspeedC) an integer indicating which switch 
block to execute. The open routine checks the dCtlStorage field 
of our device control entry to make sure storage has been 
allocated, and allocates it if not. Since we read in our storage 
from the Printer Resource File, we have to find the “Blessed 
Folder" first. Iuse SysEnvirons to do this, then OpenRFPerm to 
open the resource file. (SysEnvirons is available as an OSTrap 
with system 4.1 and newer, and as glue for MPW and Light- 
speedC. It will return the correct VRefNum for the system folder 
on all Macs, I have been told.) Then we read in our storage from 
the resource file. Other tasks are to check to see if other required 
initializations have been performed, and to open and configure 
the serial port. It does not hurt anything to open the serial port 
more than once, so we open it every time the open routine is 
called. Also, the serial port parameters can be changed by the 
user in our Chooser interface, so the open routine sets the serial 
port parameters to whatever was “Chosen” last. The serial port 
is never closed, to maintain compatibility with 64k ROMs. 

The driver control routine does mostof the work of hardware- 
related printer functions, as well as part of the interface to the 
Font Manager. Since this driver is used for text-only functions, 
we perform only a subset of the low-level printer driver calls here. 
When the control routine is called, the csCode of the parameter 
block determines which driver function is required. I will discuss 
first the csCodes which I do not implement. 

Printer driver parameter blocks have the usual driver control 
parameter block structure, but the fields following csCode are 
almost always three longs, IParam1, IParam2, and IParam3. A 
modified definition of the control parameter block, included in 
the master header file, is used to define these. When csCode is 
iPrBitsCtl or iPrEvtCtl, some sort of bitmap transfer to the printer 
is desired. With iPrBitsCtl, [Param] is a pointer to the bitmap, 
lParam? is a pointer to the rectangle to be printed, and IParam3 
contains resolution information (defined for the ImageWriter). 
When csCode is iPrEvtCtl, this means that either (command- 
shift-4) or (command-shift-capslock-4) has been pressed, de- 
pending on IParam1. ІРагат 1 is iPrEvtAll for printing the entire 
screen, and iPrEvtTop for printing the top window on the screen. 
If you havea printer capable of printing bitmaps in some fashion, 
then you can at this point translate the appropriate QuickDraw 
bitmap to one which your printer can handle, then simply send the 
graphics commands to your printer to do this. Doing so is the 
quickest way to get some sort of graphics capability for a non- 
Apple printer with the Macintosh. A few hours with Inside 
Macintosh and the manual for your printer should be enough to 
do this, but that is not the topic of this article... 

When csCode is iPrIOCtl, then text streaming is being used. 
ІРагат1 is a pointer to an area of memory containing characters 
to be sent to the printer. IParam2 is a long integer which tells us 
how many characters to send. We simply use these values to fill 
in the ParamBlockRec we use to communicate with the serial 
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driver, and issue a PBWrite call. Note here that I use inline 
assembly to issue the PBWrite and some other calls. I do this to 
suppress loading of libraries, and to save code size thereby. With 
LightspeedC if we wish to load PBWrite from a library, then we 
have to load in also all the PB... calls. LightspeedC compiles 
many of the Macintosh Toolbox calls into inline code, but not 
register based ones. This is partly a matter of taste, and partly a 
matter of how your development system handles things. I find 
that doing things this way helps in debugging too, since most all 
of the code I see when using MacsBug is code which I have 
written. Anyway, there is not much to handling iPrIOCu. 

When csCode is iPrDevCtl, we are being called upon to 
perform one of several printer control actions. IParam1 serves as 
an opcode to specify the desired function. All functions are 
performed here by sending Pascal strings to the printer, and the 
routine that services iPrDevCt looks up the proper string, and 
issues a PBWrite to send it to the printer. Error checking could 
be added here, and in the iPrIOCtl code, to check for possible 
serial driver or printer errors. A status call to the serial driver 
might be appropriate, or a status call to the printer, if it accepts 
these. Errors usually do not occur here, and when they do the user 
can probably detect them, but it is a nice touch if the driver does 
so also. For instance, if you are writing a printer driver for a 
printer that can inform the computer when it has run out of paper, 
then your driver could put up a dialog with an “Ош of Paper" 
message. 

An important point should be made here concerning "Device 
Independence". The philosophy of Apple is that there is a 
different printer driver for each printer, thereby providing device 
independence to applications. However, many of the printer 
functions, with the possible exception of the bitmap calls, can be 
specified to the driver in the format of resources, as I do here. 
Certainly there is no need to have a different printer driver for 
each baud rate. In my Chooser interface, I show one method of 
letting the user specify printer parameters with a dialog box. 
Another method might be to have one driver, and several user- 
selectable configuration files. For a simple text-only printer 
driver, the ability to handle many different kinds of printers is 
certainly desirable. The more functions you support, however, 
the less you will be able to do this, particularly if you decide to 
support graphics. 

The printer driver answers to one Font Manager control/ 
status call, when csCode is iFMgrCtl. The status call asks for the 
printer's “Font Characterization Table", and IParam1 points to 
where to put it. Frankly, since I only support mono-spaced fonts 
at this point, I just give it a copy of the ImageWriter Font 
Characterization Table, copied from the Font Manager Chapter 
of the Promotional Edition of Inside Macintosh. The Font 
Characterization Table gives information about how much space 
is taken up by different text styles, and how the fields are used is 
not well documented, so I have not attempted to do much with it. 
The Font Manager control call is to inform the printer driver 
which font has been selected for use, and to give the driver a 
chance to modify it. The original Inside Macintosh says IParam1 
points to an FMOutput record in this case, but use of MacsBug 
shows that it is a pointer to an FMInput record. The device field 
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of the FMInput contains an integer from one of my style dialogs, 
so I can use it to determine information which is specific to my 
driver. I use it here to determine character pitch, either 10, 12, or 
15 срі. At present, I tell the Font Manager I want Monaco 9, and 
modify the width according to character pitch. Much more 
experimentation is needed to make full use of these Font Man- 
ager calls, particularly if you want to support proportional fonts, 
or if you hope to work with applications which do fancy format- 
ting. Justification does not work very well with my driver at this 
point, partly because I do not yet know how to respond to these 
calls in the best manner. 

The driver close routine is simple. I purge the Handles to 
whatever storage I use, and set my copies of them to "nil". If your 
printer driver will only work on 128k ROM machines or better, 
or if you plan to include the RAM serial driver, then perhaps you 
would want to doa RAMSDClose at this point. The correct thing 
to do here is unclear to me, especially remembering what hap- 
pened when I had 64k ROMs and attempted to close the serial 
driver... (For those who never had 64k ROMS, the dreaded 
"mouse freeze" was the usual result.) There is usually not a 
problem here, unless the user plans to switch cables around with 
the Macintosh left on (not a good idea, anyway). 

These are the functions performed by the driver, and how it is 
put together. Most development systems provide a “template” 
for writing desk accessories or device drivers, or a main unit 
which you link your driver service routines to. In this sense, the 
driver is the easiest part of all to write, since the code header is 
already taken care of for you. If you can write a desk accessory, 


then you can write this part of the printing code, no problem. 


/* 

х XPrint.c. printer driver for daisy-wheel printers 

* for the Macintosh. 

* Earle R. Horton. August 17, 1987 

* LightspeedC source. 

* Set the project type to Device Driver, ID #2. 

* Run RMeker to put resources in printer resource file. 

* Install with Chooser. 

Ы 

8include «WindowMgr.h? /* inc. QuickDraw.h, MacTypes.h */ 
8include «EventMgr .h> 

include <DialogMgr .h> 

8include «SerielDvr.h? 

®include «FontMgr .h» 

8include «HFS.h» 

8include «asm.h? 

"define DRIVER MODULE 

8include *prglobals.h^ /* see end of this code for this */ 
/* 

* LightspeedC doesn't provide these as InLines. 
Space, I provide my own routines. 
having to link in MacTraps. 

*/ 


To save 
This way, I get around 


int HNoPurge(); 
int HPurge(); 

int HLock(); 

int CloseDriver(); 


int checkabort(); 


/* Useful constants */ 
"idef ine OPEN 0 

"def ine PRIME 1 

def ine CONTROL 2 
"define STATUS 3 
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define CLOSE 4 


üdefine SERRESET 8 
"define SERSHAKE 10 


#def ine XONCR CCchar217) 

"define XOFFCR ((сһәг2192 
"def ine RESFILEID (-8192) 
def ine PACKID (<-4080) 


gainCp, d, n) 

PrPerem *p;  /* ==) parameter block */ 
DCtlPtr d; /* ==) device control entry */ 
int n; /* entry point selector */ 


/* Check to make sure our data area was allocated. It may 
not have been if we were opened with a low-level open or even 
а device manager PBOpen() and our printer resource file was 
not opened. Note that we cannot use any of LightspeedC’s 
“global” variables until after we get our storage from the 
resource file and lock it down, making A4 point to it. This 
probably does the same thing that the prolog code attempts to 
do with the original ‘DATA’ resource created by LightspeedC.*/ 


int i; 
Handle storage; 
if(d-»dCt1Storage == nil && n != CLOSED( 
if CopenprinterfileCd) == -1)( 
PrintErr = ResError(); 
CloseDriver(d->dCtlRefNum); 
return(-1); 


) 
HLockCd-» dCt 1Storage); 
storage = d-)dCt]Storage; 


esn( 
поуеа.1 storage,ead ;; LS C uses M as the base 
movea.] (að), a4 3, for driver globals. 


if Cd->dCtIStorage != nil) switch (п2(/% dispatch */ 


case OPEN: 
openprinterf ileCd); 
Тым = (PfgX)(GetResourceC'Stng^, RESFILEID))) 
== nil 


/* open */ 


GetResource( ”5ТЕ8” ,PACKID) == nil){ 
CloseDriver(Cd-? dCtlRef Num); 
return(-1); /* Can’t run without these. */ 


LoadResource(settings); 
HNoPurge(sett ings); 
SetControlStrings(); 
ӘРорепС); 
HPurge(settings); 
settings = nil; 
prpb.ioNamePtr = prneme; 
break; 


case PRIME: /* For read/write calls, not here. */ 
break ; 


case CONTROL: /* control */ 
switch (p-»csCode){ /% Device Control Call */ 
/* p-?csCode gives opcode, and we switch on */ 
/* it to perform low-level Printing calls */ 
case iPrBitsCt!: /* Send bitmap to printer (NA). */ 
break; 
cese iPrIOCt!: /* Text streaming. */ 
iopb.ioParem.ioBuffer = (Ptr )р-› 1Param!; 
iopb.ioPerem.ioReqCount = р-› 1Param2; 
esn( 
lea iopb,ad 
PBWrite 
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) 
break; 
cese iPrEvtCtl: /* Screen print Cemd-shift 4, NA.2*/ 
break; 
cese iPrDevCtl: /* CR, LF, FF, etc. */ 
devicecontrol(p-? 1Рагап 1); 
break ; 
cese iFMgrCtl: 
/* Font manager font table modify request. p-?lPerem! is 
а pointer to en FMInput record. СІМ says we get an FMOutPtr 
here, but MacsBug says we get a pointer to ап FMInput. I go 
with MacsBug.) In addition, the integer following p-?lPeremi 
contains our driver reference number and а private byte we can 
use internally. The application first does something to 
determine the characteristics of fonts in our printing 
GrafPort. The Font Manager calls our status routine with 
csParam = 8 and we give it a “font characterization table”. 
The Font Manager selects a font, and calls our control routine 
to confirm the choice. We change it to Monaco 9, horizontal 
scaling. If you need to support proportional fonts, then you 
have to do something about it here and in the printing code, 
too. Good Ба x/ 


FMInput *fontset; 
fontset = (FMInput *)p-»lPerem!; 
fontset->family = monaco; 
fontset->face = 0; 
fontset-»needBits = 0; 
fontset-»numer = noscale; 
fontset-»denom = noscale; 
if(fontset-»device == IDEV10)( 

fontset— size = 10; 

fontset-?numer .h 

fontset-?denom.h 


1; 
6; 


else if Cfontset->device 
fontset->size = T; 
fontset->numer .h 
fontset-?denom.h 


IDEV 15){ 


= 5; 
= 6; 
г fontset-»size = 9; 
break ; 


default: 
break; 


break; 

case STATUS: 
switch (p-^csCode)( /% Device Status Call */ 
/* р-› сѕбоде gives opcode, and we switch on */ 
/* it to perform low-level Printing calls */ 
cese iFMgrCtl: 


/* Font manager font table request. Help out the Font 
Manager. р-›1Рагат1 is а pointer to an area in memory in which 
to put а copy of the information describing our font capabili- 
ties. р-› 1Рагат2 has an integer in its high order word which 
contains the “resolution” to use, set in а style dialog with 
the user. We say we have different horizontal resolutions, 
based on the number of characters per inch used. I believe 
this gets called whenever the application does a GetFontInfo ) 
or StringWidthC) or whatever for the first time in one of our 
printing GrafPorts. Possibly also when the application tries 
to change the font style. */ 


*(Cfontab %)р-› 1Рагат1) = myfonts; 
break; 

default: 
break; 


break; 
case CLOSE: /* close */ 
if(storage != nil){ 
HPurge(storage ); 
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prinitCnane) 
ie name; /* ROM, RAM serial driver? Who cares? */ 


d->dCt1Storage = nil; 
break; 


/* done */ 


return(0); 


SPopenC) /* Open serial driver and configure it. */ 


/* Use low-level ROM routines. */ 


( 
PermBlkPtr pb; 
int . serconfig; 


pb = &iopb; 
switch (ррог+) ( /* get the correct port */ 
case 0: /* modem port */ 


ifC!phone) ( 
prinitC*\p.Adut”); 


phone = TRUE; 
drivernum = AoutRefNum; 
break; 

case 1: /* printer port */ 


ifC!printer) ( 
prinitC”\p.B0ut”); 
printer = TRUE; 


drivernum = BoutRefNum; 
break; 


/* set up the io parameter block for writing to the 


serial driver. A control] call resets the baud rate */ 


pb-? ioParam. ioRefNum = drivernum; 
pb-? ioParam. ioCompletion = nil; 
CCcntr1Param *)pb)-?csCode = SERRESET; 
serconfig = data8 + noParity + stop20; 
serconfig += mybauds[pbaud] .rate; 
(Centr 1Param* dpb )-› csParam(8] = serconf ig; 
asn ( 

move. l pb, ad 

PBControl 


) 
8def ine shake CCSerShk*)&CCentr 1Param* pb )-» csParam(8]) 


shake-?errs = FALSE; 
sheke-?evts = FALSE; 
shake->fDTR = FALSE; 
Shake-?fInX = FALSE; 
if (XonXoff && CtheWorld.machineType >= envMachUnknown)){ 
shake->fX0n = TRUE; 
shake->fCTS = FALSE; 
sheke-?xOn = XONCR; 
Sheke-?xOff = XOFFCR; 


else ( 
Sheke-?fXO0n = FALSE; 
shake-)fCTS = TRUE; 


) 
ССспіг1Рагат *)pb2-»csCode = SERSHAKE; 
esn( 

move. pb, ad 

PBControl 


“undef shake 


pb-? ioParam. іоРоѕМоде = 0; 
pb-? ioParam. ioPosOffset = 9; 


/* Open a driver by name. */ 


iopb. ioParam. ioNamePtr = name; 
iopb. ioParam. ioCompletion = nil; 
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lopb.ioPerem.ioPermssn = 0; 


asm { 
lea iopb, ad 
PBOpen 
) 
/* 


* Set printer control strings based on our STR" resource. 
*/ 
ашы 


unsigned char *strptr; 
unsigned char **mystrings; 


mystrings = (unsigned char **)GetResource( “ТЕ ^ PACKID2; 

if(mystrings != nil){ 
LoadResource(mystr ings); 
copystr( (strptr = (*mystrings)+2) , prifstr); 
copystrC (strptr += (*strptr) + 1) , prinitstr); 
copystr( (strptr += (*strptr) + 1) , prtopstr); 
copystr( (Cstrptr += (*strptr) + 1) , preopstr); 
copyustrC Свігріг += (*strptr) + 1) , preofstr); 
decode(prifstr); 
decode(pr initstr); 
decode(pr topstr ); 
decode(preopstr ); 

decode(preofstr); 


decodeCstr) 
unsigned cher *str; 


register unsigned char i,count; 
count = 1; 
forCiz0;str(01-i**;2( 
if (str[i] == '*^) strf{count] = 31 & str(**i]; 
else str[count] = str(il]; 
count**; 


str(9) = count - 1; 


/* 
* This is for copying PASCAL strings. Simple. 
*/ 

copystr(serc, dst) 

ия cher *src,*dst; 


asm ( 
сіг.1 dð 
nove.1 9гс,80 
nove.1 (454,81 
move.b Сай), dð 
100p: 
move.b Сай)+, Са1)+ 
абга d2,6100p 


devicecontrolCcode) /* printer device control calls. */ 
long code; 


switch(code ) { 

case lPrReset: 
pr intstr ing(pr initstr); 
break; 

case lPrPageEnd: 
printstring(preopstr); 
break; 

case lPrLineFeed: 

case IPrLFSixth: 

case IPrLFEighth: 


printstring(pr Ifstr); 
break; 

default: /% Unknown parameter. */ 
break; 
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) 


) 
printstring(string) /* printer control string to serial 


driver. */ 


rela char *string; 


їоро. ioParam. ioBuffer = (Ptr )(stringt1); 
їоро. ioParam. ioReqCount = Clong)(string(8]); 
asm ( 

lea iopb,ad 

PBWr ite 


/* Find the system folder, and open our printer resource 


file, if we can. Fill in & global SysEnvRec, which might be 
useful for other stuff. */ 


int openprinterf ileCd) 
Cor d; 


SysEnvRecmyWor 1d; 
StringHandle ourname; 
int therefnun; 
Hendle storage; 


ifCd-»dCt1Storage != nil) 

HPurge(d->dCt1Storage); 
ourname = (StringHandleGetResource( ‘STR ',0хЕ000); 
LoadResource(ourname ); 
HNoPurgeCourname); 
HLockCourname); 
SysEnvirons( 1,&myWor 1d); 
if CmyWorld.machineType >= envMachUnknown) 

therefnum = OpenRFPermC*ourname, myWorld.sysVRefNum, 


/* Get resource file name. */ 


fsCurPerm); 


else 
therefnum = OpenResF ileC*ourname); 
HPurgeCourname ) ; 
if Ctherefnum != -1)( 
d-)dCtiStorage = (Handle )GetResource( ‘PREC’, RESFILEID); 
ifCd-»dCtiStorage != nil) 
LoadResource(d-? dCt Storage); 
DetachResource(d-) dCt1Storage); 
HNoPurgeCd-? dCt 1Storage ); 
HLock(d-) dCt 1Storage); 
storage = d-»dCt'Storage; 
asm ( 


movea.! storage,a0;; LightspeedC uses А4 
movea.1 (ай), а4 j; for driver globals. 


theWorld = myWorld; 


return Ctherefnum); 


int HNoPurgeCc) 
cher *c; 


esn( 


nove.1 c,aĝ 
HNoPurge 


) 
int HPurgeCc) 
cher *c; 

esn( 


move. l с,а0 
HPurge 


) 
int HLockCc) 
cher *c; 


esn( 
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nove. c,o0 def ine CHARWIDTH6 
HLock “def ine CHARHEIGHT 11 


) “define iPrPrivate 99 
int CloseDriverCrefnun) 


int refnum; “define VERSION 3 
ParamB lockRec closepb; “define DEBUG 
esn( "if _DEBUG 
lea closepb, ad "def ine DEBUG asm({\ 
nove.w refnum,24Ca0) Debugger V 
сіг.1 12Ce0) 
PBClose "else 
move.w 16(а0), 49 8def ine DEBUG 
endif 
) “define ІПЕУІ0 0хҒ001 
uu cT S 2 REIR NP EHE NS » 
OLTRE ris DEVE bes 
def ine nil OL 
include «PrintMgr.h? /* HIgh order byte of IDEV is -3 for printer driver, low order 
t include «Dev iceMgr h byte is device specific. I use it to determine character pitch 
include «FileMgr h) for daisy wheel devices and dot matrix in draft mode. */ 
ninclude «Environs.» Sdef ine SETUP-CHD "ер, 
define DIRTY ØxFFFF def ine CLOSE CMD ‘Clos’ 
/* LightspeedC doesn’t do this exactly right for a Printer 


& | е , 
control call. */ def ine OPEN_CMD ‘Open 


typedef struct typedef struct( /* Font characterization teble */ 


QElenPtir qL ink; ү 2 /* for use by the Font Manager . х/ 

Мн; er. SignedByte 501613); 

Bim. чо SignedByte italic[31; 

ProcPtr  ioCompletion; SignedByte notused([31; 

OsErr ioResult: s SignedByte outline[3); 

StringPtrioNamePtr; SignedByte shadow[31; 

int ioVRefNum: ` SignedByte condensed[3]; 

int — ioRefNun: SignedByte extended[3]); 

oe SignedByte underline[3]; 

int — csCode; )fonteb; 

long Param; , 

long  lPerem?2; js 
mo M das * Shared storage, def ined and initial ized by the driver code, 
) PrPeren; eccessed elsewhere. */ 
"define WIDTH 164 /* 1а bombe if not a multiple of 4 */ def н ONUS 
"define NROWS 66 /* 11 inches * lines per inch. */ tupedef struct( 
typedef struct beuds( dif 

M TE tifdef DRIVER. MODULE 
)BAUDS f BAUDS mybauds[] = (  /* Baud rate constent table. */ 
tupedef struct ( ( baud300, *p300^), /* Should use a string list. */ 
Mnt dirty; epe i /* a these are numbers, so I */ 

( ; U " *), / Think it’s OK. */ 
osi рел к ( baud1880, «\р 1800), /* This has to Бе the FIRST */ 
t odel еш i ( baud2400, *Xp2400"), /* driver global to be declared, */ 
Mint dummy (51; ( baud3600, “\p3600"), /* since it is also used by our */ 
д 


( baud4820, “\p4800°)}, /* PACK -4096 resource, which */ 
( baud7200, *Xp7200"), /* needs to find it at the head */ 
( baud9600, “\p9600"), /* of PREC -8192. */ 


) pconf ig, *Pcfg, **Pfg; 
/* Be a real Mac cowboy, access data by the handle. */ 
“define pport  CC*settings2-»dummy[2)) 


@ ” 
define pbeud — (C*settings)-?dummyL 11) r beud19200, “\р19200°) 
define XonXoff  (C*settings)->dummy[2]) 

/% Үееееее-Наһ !! I don’t even lock it! */ Pfg settings = ak 
typedef struct ( /* Structure description of STR® */ nil, /ж m */ 

int numstrings; /* resource. */ Ü /* eT x/ 

unsigned char thestrings[]; 2 /* Ад 7 
)stringlist, *#StrList; nil, уж joCmdiddr — */ 
“define КЕ5110 (-4080) TM * ioCompleti x 
"define RES2ID (-8192) С» OI ари 
8def ine ILLEGAL Ox4AFC nil, /% ioNemePtr — */ 
typedef unsigned cher 51736361; И í 
"def ine HREZZ 72 ЛА M, a 
define HREZZ18 60  /* For 10 cpi. */ Т cstode */ 
"define HREZZ12 72  /* For 12 cpi. x/ aL, OL, OL /* lPeren(1-3)] */ 
"define HREZZ15 98  /* For 15 cpi. */ ); 


"define VREZZ66 /% 6 lines of printed text per inch. */ 
6 


define lines_per_inch Str36 ргпаве = sPrDrvr; 


178 © The Essential MacTutor, Vol. 3 


else 
BAUDS mybauds[ 101; 
Pfg settings; 
PrParam prpb; 
$tr36 prneme; 
Sendif 
PeremBlockRec iopb; /* For writing to serial driver. */ 
ifdef DRIVER. MODULE 
static int phone =FALSE; 
static int printer =FALSE; 
telse 
int phone; 
int printer; 
"tendif 
int drivernum; /* RefNum of serial driver to use. */ 
Str255 prinitstr; 
Str36 prifstr; 
Str36 prtopstr; 
Str36 preopstr; 
Str36 preofstr; 
#ifdef DRIVER MODULE 
static fontab myfonts = ( 


); 
static Point noscale = (0х0001,0х0001); 
telse 

fontab myfonts; 

int MyRes(3]; 

Point noscale; 
“елді” 

Str255 stringbuf ; 

int topnergin,nlines; 

TPrint Print; 

int pagenum; 

SysEnvRec theWor d; 
8ifdef DRIVER. MODULE 
telse 
JDstorage, *DPstorage, **DHstorage; 
endif 
Sdefine SHEETDIALOG (-8193) 
"define DONEITEM 1 
"define STOPITEM 2 


*Style and job dialogs for Daisy printer driver 
*Chooser interface dialog 
*Settings, strings, resource file BNDL, ICN®, and FREF 


8 321 28 381 
к 


src:Printer:dialogs.rere 
???????? 


Туре DLOG BtnItem ;; 2 
, 8191 9 395 29 455 
Job Cancel 


50 20 136 493 


Invisible NoGoAway StetText Disabled ;; 3 


1 ;; procID 9 6 24 145 
1 ;; refCon Daisy 
-8191 
StatText Disabled ;; 4 
Type DITL 38 5 46 89 
ee Page Range: 


Radiol tem 22-5 


BtnIten  ;; 1 30 93 45 138 
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All 


RedioItem 6 
30 140 46 200 
Ғгов: 


EditText Disabled ;; 7 
30 205 46 237 


StetText Disabled ;; 8 
30 242 46 270 
To: 


EditText Disabled ;; 9 
30 272 46 304 


StetText Disabled ;; 10 
55 5 71 89 
Copies: 


EditText Disabled ;; 11 
55 95 71 127 
1 


StetText Disabled ;; 12 
55 145 71 200 
Feed: 


Radioltem 2; 18 
55 205 70 303 
Continuous 


Radioltem 3, M 
55 305 71 425 
Sheet Feed 


Type DITL 
Printer Dialog Template, –4080 
21 


x 1 

BtnI tem Enabled 
224 103 248 173 
Save 


x 


2 
StatText Enabled 
149 7 165 129 
Bottom of page 


* 3 

StatText Disabled 
6 91 23 219 
Printer Port Setup 


* 4 

StatText Disabled 
38 6 46 51 

Port: 


* 5 

RedioItem Enabled 
30 57 46 157 
Modem Port 


x 6 

RedioItem Enabled 
30 165 46 265 
Printer Port 


“ 7 
StatText Disabled 


57 6 73 81 
Baud Rate: 


* 8 

BtnItem Enabled 
57 98 73 143 
runtime 


x 9 

StatText Disabled 
58 153 74 300 

(Hit me for more.) 


х 10 

StatText Disabled 
83 5 99 122 

Line Terminator 


z 11 

EditText Enabled 
83 128 99 320 
runtime 


x 12 
EditText Enabled 
105 128 121 320 
runtime 


% 13 

EditText Enabled 
127 128 143 320 
runtime 


* 14 

EditText Enabled 
149 128 165 320 
runtime 


x 15 

EditText Enabled 
171 128 187 320 
runtime 


* 16 

StetText Disabled 
195 6 121 123 
Initialize 


x 17 

StatText Disabled 
127 7 143 124 

Top of page 


* 18 

StatText Enabled 
171 8 187 121 
End of file 


x 19 

RadioI tem Enabled 
197 8 213 121 
CTS 


% 26 

RedioItem Enabled 
197 165 213 265 
X0n/XOff 


x 21 
BtnItem Enabled 
224 183 240 253 
Cancel 


Type DLOG 
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Printer Conf ig Вох,-4080 
Serial Port Configuretion 
40 80 296 424 

Invisible NoGoAway 

1 ;; procID 

9 ;; refCon 

-4080 


Type STR 
Right Button,-4092;; Chooser right button title 
Setup... 


Type STR 
List 18be1,-4091 ;; Chooser list label 
Serial Printer Driver 


Туре Stng = GNRL 
Printer Settings, -8192 
H 


0001 0002 0000 0000 ;; Printer port, 1200 baud, no Xon/Xoff 


Type 5789 ;; String list for EOL, EOP, BOP strings 
Printer control strings,-4080 ;; Tandy DMP-110 
5 
“M 2; End of line 
“СИ. Initialize printer 
;; beginning of page 
*L 3, end of page 
2; end of document 


Type BNDL 
, 128 

DasY 0 
ICN# 

0 128 
FREF 

0 128 


Type DasY = STR 


0 
д 
Version 0.20000 1 


Type FREF 
‚ 128 
PRER 0 


Type ICN® = GNRL 
ICN, 128 
H 


00000000 TFFFFFFE 40000002 40000002 
40003802 40004582 400 1С642 40024442 
40042842 4002 1Ғ82 4003ҒЕ42 40043042 
40025С82 400 19442 40009242 40009382 
40381202 403С4С02 40 18002 40038002 
400 16002 4002F002 40047002 40087002 
40080002 43ҒҒС002 42004002 41ҒҒ8002 
408 10002 40420002 TFFFFFFE 00000000 
00000000 TFFFFFFE 7FFFFFFE 7FFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE 7FFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE 7FFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE TFFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE TFFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE T7FFFFFFE 
TFFFFFFE 7FFFFFFE 7FFFFFFE ТЕҒҒҒҒҒЕ 
TFFFFFFE 7FFFFFFE 7FFFFFFE 00000000 
* Printer style dialog template 
Type DITL 

278192 

8 


BtnIten 221 
10 319 30 379 
OK 
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Btni tem P 
10 390 30 450 
Cancel 


StatText Disabled ;;3- 
10 5 30 308 
Daisy: 8.5" by 11" 


RedioItem Enabled ;;4 
10 5 90 100 
10 cpi 


RedioItem Enabled ;;5 
TO 120 90 180 
12 cpi 


RedioItem Enabled ;;б 
70 200 90 260 
15 cpi 


RedioItem Enebled ;;7 
40 5 60 150 
Straight up 


RedioItem Enabled ;;8 
49 155 60 300 
Sideways 


* Style dialog box 


31 20 120 488 
Invisible NoGoAway 
1 ;; procID 

1 ;; refCon 

-8192 


Type DLOG 

Next Page Box,-8193 
Next Page 

48 51 100 300 
Visible NoGoAway 
1;; procID 

8 ;; refCon 

-8193 


Type DITL 
Next Page Template, -8193 
3 


ж 1 

BtnItem Enebled 
30 60 46 140 
Done 


* 2 
BtnItem Enabled 
30 160 46 240 


Stop 


* 3 

StatText 

8 8 24 292 

Deisy: Insert Next Sheet 
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Advanced Mac'ing 


Printer Resource File, Part II 


Part 3: The dialogs, or Communicating with an 
application 
The routines which handle the Style (“Page Setup...”) and 
Job ("Print...") dialogs are contained in a resource of type 
‘PDEF’, ID 4. These routines communicate user choices to the 
application via a data structure known as the “Print Record", 
which is always accessed by its Handle. The dialog routines also 
provide to the application the ability to modify the dialogs, and 
insert its own event filters and item handlers. Because of this, the 
structure of the dialog handling routines is quite rigid. In order 
to understand the necessity for this way of doing things, it will be 
necessary to obtain a copy of Macintosh Technical Note #95: 
"How to add items to the print dialogs." This Technical Note 
provides an excellent description of the workings of the print 
dialog code, and it is not my intention to summarize it here. It 
would also be wise to print out the header file which defines the 
Print Record data structure for your development system. This 
part of the Printer Resource File is quite possibly more compli- 
cated and harder to understand than even the printing code. 
The dialog handling code starts off with the following 


header: 

bre.w PrintDefault 
bra.w  PrStiDialog 
bra.w  PrJobDialog 
bra.w  PrStlInit 
bra.w  PrJobInit 
bre.w PrDigMain 
bre.w  PrValidate 
bre.w X PrJobMerge 


This code provides several levels of support for applica- 
tions, and we must be careful to allow each application to use it 
in the way it is accustomed to. Each level of support implies 
certain information which is supplied by the Printer Resource 
File, and other information which the application wants to fill in 
itself. If an application calls PrintDefault, then it wants us to fill 
in all the fields of the Print Record passed to PrintDefault with 
suitable default values for the printer. (Note to C programmers 
who cut their teeth on UNIX: Print Records are accessed by the 
Handle; get used to accessing objects by the Handle RIGHT 
NOW.) An application may call PrintDefault, and no other 
routines in this overlay. For this reason, the default print record, 
contained in ‘PREC’ 0, should provide a reasonable page format, 
andall the fields should have values which imply behavior which 
the user expects from, say, the ImageWriter driver. My default 
Print Record is similar to that used by the ImageWriter, but I have 
set all margins to the edge of the page. Study the Print Record 
data structure, and those portions of Inside Macintosh which tell 
application programmers how to use it. 

Assume that the Print Record is contained in a data structure 
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Fig. 2 Our Driver has a set-up option! 

named "uPrint". uPrint.iPrVersion is equal to 3, the current 
version of the Printing Manager. uPrint.prInfo.iDev contains -3 
in its high-order byte, and a device-specific byte in its low-order 
byte. I use the low-order byte to keep track of whether the 
character pitch is 10, 12, or 15 characters per inch. The 
ImageWriter and LaserWriter drivers use this field for resolution 
information. My driver will be called by the font manager with 
this byte, and my text drawing code will use the value to 
determine where to place text in its output buffer. 
uPrint.prinfo.iVRes and uPrint.prinfo.iHRes provide the 
printer's vertical and horizontal resolution, in units of pixels per 
inch. I provide values here which are close to those used by the 
ImageWriter and the standard Macintosh screen, thus insuring 
that font choices made by the Font Manager will be similar to 
what my printing code expects. uPrint.prInfo.rPage is the "Page 
Rectangle" of the specialized GrafPort used by applications in 
printing, in units of pixels per inch. uPrint.rPaper is the "Paper 
Rectangle" and encloses the Page Rectangle. 

If you want to provide applications with maximum flexibil- 
ity in choosing margins, then set uPrint.prInfo.rPage equal to 
uPrint.rPaper. Remember that the lengths of the sides of 
uPrintrPaper, divided by the appropriate resolution, should 
equal the physical paper size, so that the application knows how 
big the paper really is. The conventional way to do this is to inset 
uPrint.prInfo.rPage inside uPrint.rPaper, thus providing default 
margins. In this case, the origin of the coordinate system is the 
top left corner of uPrint.prInfo.rPage, and the top left corner of 
uPrint.rPaper has negative coordinates. An application may 
attempt to print outside of uPrint.prInfo.rPage, but never outside 
of uPrint.rPaper. If you set up these fields with margins, you 
should probably print in the margins when requested, and if 
physically possible. Attempts to print outside the page rectangle 
should, of course, be ignored. 

The prStl sub-record contains four types of information. 
Why these four should be grouped here, I don't know. 
uPrint.prStl.wDev is private, you may put whatever you want 
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here. The next two fields, uPrint.prStliPage[VH], give the 
physical dimensions of the paper, in units of 1/120 inch. Make 
sure that these agree with the page rectangle, or something 
strange may happen. uPrint.prStl.bPort contains which serial 
port to use. I do not use this field, but rather obtain this 
information from my Chooser device interface. The next field is 
uPrint.prStl.TFeed, and indicates the paper field mechanism. 
That this is in the style sub-record makes little sense, since the 
information is set from the Job dialog. It may be in here for 
historical reasons, and it is certainly too late to change it now. 

uPrint.prInfoPT is a copy of uPrint.prInfo; structure assign- 
ment is a convenient way to copy one onto the other. 
uPrint.prXInfo contains information used in spool printing, and 
you can either put in reasonable values or zeroes here if you don't 
do spool printing (this example does not do spool printing). 
uPrint.prJob contains information particular to a particular print 
job. uPrint.prJob.iFstPage and uPrint.prJob.iLstPage give the 
first and last pages to print. The printing code is responsible for 
keeping track of which pages get printed in draft printing, and not 
the application. uPrint.prJob.iCopies is the responsibility of the 
application; if the user wants multiple copies of the page, then the 
application must print them. uPrint.prJob.bJDocLoop is always 
bDraftLoop, since we only support draft printing. 
uPrint.prJob.pIdleProc is a ProcPtr to a background procedure to 
run during printing. The default value is ‘nil’, and the application 
may put its own ProcPtr in here. Usually this procedure just 
checks for a user abort, although it can do anything except use the 
Print Manager (thankfully, we don't have to make the Print 
Manager reentrant!). 

The rest of the fields of the Print Record are either for spool 
printing or are private. If you need to store extra information 
here, then use the uPrint.printX array. The only private field I 
have found it necessary to use is uPrint.prInfo.iDev, although 
you may need to use more. 

When an application calls PrValidate, it has a completely 
filled in Print Record obtained from either PrintDefault, the 
dialog handling routines, or perhaps fabricated by the application 
itself. Check the Print Record here to see that the resolution is 
correct, and verify that the page size can be handled by the 
printing code. If the Print Record cannot be used, use PrintDe- 
fault to convert it to the default values, and return TRUE. 
Otherwise, do nothing and return FALSE. 

PrJobMerge is used when it is desired to copy fields of from 
Print Record to another, such as when printing multiple files. 
Copy the job sub-record and update the printer information, band 
information, and paper rectangle in the destination print record. 
These instructions are from Inside Macintosh and are admittedly 
somewhat vague, since I don't really know what "update" means 
here. I just copy the stuff which requires updating from the 
source Print Record. 

Read Technical Note 4/95 at this point to see how the dialog 
routines work. There is not much room for orginality in either 
PrDigMain, PrStlDialog, or PrJobDialog. The dialog initializa- 
tion routines fetch the appropriate dialog template from the 
Printer Resource File, usually with GetNewDialog, and set the 
initial values of radio buttons, check boxes, and the like. The 
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Printer Port Setup 
Port: @ Modem Port © Printer Port 
Baud Rate: 
Line Terminator 


Initialize ^[c^[1^[0^[a2 


Top of page 


шм | _ 


End of file 


Q) CTS © uon/Woff 


Fig. 3 Our Set-Up dialog sets baud rate, control chars 
dialogs are not actually drawn until PrDlgMain. Keep in mind 
that the application may be modifying the dialogs after your 
dialog init routine, then passing the pointer to the modified dialog 
to PrDigMain. This means that your dialog event filter and item 
handler may be called after routines supplied by the application. 
The Print Record associated with the TPrDlg dialog object is not 
modified unless the “Done” or “Ok” button is hit (item number 
1 in the dialog). The fDolt and fDone fields signal to PrDigMain 
whether the Print Record should be validated or not, and whether 
the cancel or finished button has been hit. 

My style dialog contains three radio buttons for printer pitch, 
and two check boxes for portrait and landscape mode. The item 
handler sets the appropriate control values when one of these is 
hit, and records the user choices only if the Ok button is hit. It gets 
information about which values to put in the print record from the 
control settings. This code only supports 8 1/2" by 11" paper, in 
one of two orientations. If you want to provide more paper sizes, 
and perhaps controls to set the margins, then provide more dialog 
items and a place for the item handler to get the other settings. 
Several paper sizes could be provided merely by having several 
Print Records stored in the Printer Resource file as ‘PREC’ 
resources. Remember to fill in only the fields having to do with 
paper size, orientation, and page size when doing the style dialog. 
The device field can also be set here, since it is a private field. 
After the item handler fills in these fields, the application's item 
handler, if used, gets a shot at the dialog object and the Print 
Record, then PrDigMain cleans things up and disposes of the 
dialog object. 

The job dialog is handled in identical fashion to the style 
dialog. The item handler fills in the job record from the user’s 
choices. The job dialog, in comparison to the style dialog, is 
pretty well standardized. Provide a mechanism whereby the user 
can specify multiple copies and a page range, as well as sheet or 
fanfold feed. After filling in the appropriate fields in either the 
styleor job dialogs, set the value of the fDone and if necessary the 
fDolt fields of the Print Dialog object, and return. PrDlgMain 
will validate the Print Record if о is set, and return the value 
of fDoIt when done. This is how the application knows whether 
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Fig. 4 Our Print Setup dialog box 


the Print Record has been selected by the user and, in the case of 
the job dialog, whether to proceed with printing. 

The standard print dialogs are not a good place from which 
to obtain information which is not part of the regular 
ImageWriter or LaserWriter dialogs, since the application is not 
required to use them. If you need information which is particular 
to only your printer driver, then use the Chooser device interface 
instead. 

Part 4: The high-level printing code 

This is the part everybody has been waiting for, I'm sure of 
it! How to translate QuickDraw drawing commands into the 
printed word (or even pretty pictures). The code found in the 
'"PDEF' resources 0, 1, 2, and 3 does exactly this. Each one of 
these resources starts with an offset table to the four externally 
callable routines. 


bra.w PrOpenDoc 
bra.w PrCloseDoc 


bra.w PrOpenPage 
bra.w PrClosePage 


Applications use these routines to print a document in the 
following manner: 

a) Call PrOpenDoc to get a printing GrafPort to draw in. 

b) For each page in the document: 

i) Call PrOpenPage to reinitialize the port. 
ii) Draw in the printing GrafPort, using 
ordinary QuickDraw commands. 

iii) Call PrClosePage to signal that the page 
is done. 

c) Call PrCloseDoc to dispose of the printing GrafPort. 

PrOpenDoc is just like any of the routines which create anew 
GrafPort for the application to draw in: NewWindow, for ex- 
ample. The port is customized for printing, however, by means 
of ProcPtrs which point to our drawing routines. In addition, we 
get four long integers to play with as we see fit. My printing code 
works in the following fashion: Attempts to draw text in the 
printing port results in the text being stored in a big rectangular 
array of characters. When a page is completed, the application 
signals this to the printing code, and the text is sent to the printer, 
all at once. I do this because it is the easiest way for me to do it, 
it avoids keeping track of the print head, and it allows me to 
emulate a reverse line feed. Think about it: an application may 
print some text, then attempt to move up the paper, rather than 
down. If I keep all the text in an array, then I don't have to figure 
out how to reverse the direction of paper travel. 

The way I do things in this code depends to some extent on 
the demands imposed by this method of printing. This method is 
fine for text, but I can think of one disadvantage when you (or I) 
want to do graphics. Memory on a Macintosh is finite. We 
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cannot expectto print in high resolution on a dot matrix 
printer by first buffering up a bitmap of the whole page, 
especially when the Macintosh gets a real multi-proc- 
ess capability operating system. In order to handle 
graphics properly, one has to develop the routines to do 
either draft mode printing or spooling. It’s a good thing 
for me I don’t have to come up with them for this 


article! Either true draft mode or spool printing will have some 
similarities to the printing method I employ here, but both will 
require more bookkeeping. To summarize, my printing code is 
a good start, and is good for text, but can only go so far. 

Central to printing is a data structure known as a TPrPort. 
This is merely a GrafPort, with a QDProcs structure, four longs, 
and a pair of Booleans added. A TPrPort is accessed by pointer, 
or TPPrPort. An application obtains a TPrPort to draw in by 
calling our PrOpenDoc routine. It must pass to PrOpenDoc a 
valid Print Record, and may pass us one or two storage pointers. 
If we get a pointer to storage to use for the printing port, then we 
fill out the TPrPort using the application’s storage, and flag that 
we did so in the fOurPtr field. Otherwise, we obtain a pointer to 
the required storage, and begin to initialize the printing port. This 
is a fairly complicated process, and I only handle text! I also 
obtain storage for my output buffer, and store the pointer in the 
IGParamá private field of the printing port. The process is given, 
step by step, below. 

First, obtain from NewPtr sufficient storage for the text 
output buffer and the printing port. If storage is not available, 
stuff the constant iMemFullErr into the low memory global 
PrintErr and return ‘nil’. A side note may be appropriate here. 
PrintErr is the integer located at 0x0944. According to some 
early documentation I have, PrintErr is only part of “PrintVars: 
10 print code variables [16 bytes]" stored starting at this location. 
Presumably, if you are writing a printer driver, then you own all 
16 bytes. Iam reluctant to use any of these, however, until I find 
out how Apple uses them. PrintErr is the only variable in 
PrintVars I can find documentation for. Accordingly, the only 
use I make of PrintVars is to check PrintErr for user abort, and to 
stuff it with an error code if I have to. I don’t need low memory 
globals, however, since I can share storage with my driver. The 
function DrvrStorage returns a pointer to the printer driver’s 
private storage, and I access the driver variables from within my 
printing code. Programmer’s advice: don’t use low-memory 
globals unless you are given no other choice, and you really know 
what they are for! 

After obtaining a pointer to the driver's private storage, stash 
some useful information there for later use. A copy of the entire 
Print Record should be enough, but I also take this opportunity to 
calculate the number of lines per page, and set a page number 
counter to 1. Initialize here any information you want to save that 
is asociated with a particular printing job. At this point, we are 
supposed to save a copy of the current print record in ‘PREC’ #1 
in our resource file. Why, I don’t know. Presumably, either our 
printing code or applications will benefit from having available 
а copy of the last-used Print Record. I certainly don't use it. 

Now we open and configure the printing port. The printing 
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port is opened like any other GrafPort, just call OpenPort with the 
pointer to it. Now we customize it for printing. Whenever 
possible, use ToolBox calls to manipulate the fields of the 
printing port, rather than storing into them directly. It's easier, 
and is the recommended method. The TPrPort contains a sub- 
record, gProc, of type QDProcs: 


typedef struct ( 

QDPtr textProc, 
QOPtr lineProc, 
QOPtr rectProc, 
QOPtr rRectProc, 
QDPtr ovalProc, 
QOPtr агсРгос, 

Q0Ptr polyProc, 


/* Drew text. */ 

/* Draw а line. */ 

/* Drew а rectangle. */ 

/* Drew rounded-corner rect.*/ 

/* Оган an oval. */ 

/* Drew ап erc. */ 

/* Drew & polygon. */ 
QDPtr rgnProc, /* Drew а region. */ 
QDPtr bitsProc, /* Bit-trensfer procedure. */ 
QDPtr commentProc, /* Handle picture comments. */ 
QDPtr txMeasProc, /* Return the width of text. */ 
QOPtr getPicProc, /* Get info from 00 pict. */ 
QOPtr putPicProc  /* Stash info in picture. */ 

)ODProcs, *Q0ProcsPtr ; 


АП drawing routines which affect a GrafPort are funnelled 
through one of these thirteen routines! First, call SetStdProcs, to 
fill in the gProcs field of the TPrPort with the default QuickDraw 
primitives. Then, install ProcPtrs to pointto the QuickDraw calls 
you implement. (If we are only drawing text, we must use 
SetStdProcs to fill in the ProcPtrs we do not supply, if only to 
keep track of the Pen location for us.) I now fill in the textProc 
and tx MeasProc fields of gProcs with pointers to my text drawing 
and text measuring routines. Next, the grafProcs field of the 
printing port’s GrafPort is made to point to the gProcs field of the 
printing port. The device field of the GrafPort is filled in with the 
iDev field of the Print Record. This will be used later by our 
driver when it is called by the Font Manager. 

Set the portBits.bounds rectangle of the printing port to an 
empty rectangle, so QuickDraw routines will not try to set bits in 
it. (If you are doing graphics printing, it is up to you how the 
port's bitmap is handled.) Call SetPort to make the printing port 
the currentport. Set the portRect to be equal to the page rect from 
the printing record, using PortSize. Using MovePortTo, translate 
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the printing port's coordinate system so that the upper left corner 
of the paper is the global origin, if you desire to allow printing on 
the entire page. We will use LocalToGlobal later to find the 
correct location to place text. Do this even if you consider the 
page rectangle to be equal to the paper rectangle, since an 
application may create its own Print Record. The application's 
page rectangle and paper rectangle might be anything which we 
allow in PrValidate, and are not limited to values which we 
supply in the PDEF 4 routines. 

Issue a reset command to the printer driver. Initialize 
whatever variables you need to maintain throughout a printing 
job. If you use a buffer, clear it out. Save a copy of the Print 
Record in resource ‘PREC’ #1, in case anybody is still interested. 
If the application hasn’t installed a pointer to an idle procedure, 
install one of your own. (The default idle procedure checks for 
command-'.' and aborts printing if it finds one.) Return the 
pointer to the printing port to the application when all tasks are 
complete. 

The QuickDraw primitives which I replace in the printing 
port are StdText and StdTextMeas. All QuickDraw text drawing 
routines are glue tocall StdText. Most, but not all, routines which 
determine the width of text call StdTextMeas. These routines 
work in my printing port as follows: 

When MyStdText is called, it first calls GetPen to get the 
current QuickDraw Pen location. The device field of the printing 
port is used to find the width of a character. Since I only support 
mono-spaced fonts, I have but three values for the width of a 
character. I call Local ToGlobal to translate the pen location from 
local (page) to global (paper) coordinates. Characters which are 
to be printed are stored in a big array of lines, and the global pen 
location is used to determine the starting array index of where to 
put them. Once the proper line and offset is found, a call to 
BlockMove stashes the text for later printing. Finally, a call to 
Move is used to update the pen location by the proper horizontal 
offset. Note: I have "drawn" text, therefore I have moved the 
QuickDraw pen. The total horizontal offset depends upon the 
character pitch, as determined in the page setup dialog. 

When MyStdTextMeas is called, I am being asked "How 
wide is this chunk of text?" I am 
passed a pointer to a text buffer, an 
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ШИН integer telling how many characters 


Daisy 
Page Range: (ӘНІ О From: [1 о: 
Copies: |n | Feed: 


The quick broun fox. 
The quick broun fox. 


4 Fig. 5 Print Dialog 
The quick broun fox. - 


@ Continuous © Sheet Feed 


Eum B will be drawn, a pointer to a 

9 Fontinfo record, and two scaling 
Points. The idea here is that I now 
get an opportunity to modify the 
font information if my printer can- 
not supply exactly whatis asked for. 
I change to font information to re- 


: . . flect a constant size font, and mod- 
ify the two scaling points according to what is in the GrafPort 


device field. Numer.h over denom.h gives the horizontal scaling, 
and numer.v over denom.v gives the vertical scaling. I return the 
width times the number of characters. The width depends upon 
the character pitch, as in MyStdText. If your printer has a 
proportional font, then you will have to be considerably more 
sophisticated here, and in your StdText routine, too. 
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You may install as many QuickDraw primitives in the 
gProcs field of your printing GrafPort as your printer, and your 
programming abilities, can handle. If you want to attempt 
graphics printing ona dot matrix printer, then mostof the routines 
you install will be involved with translating some QuickDraw 
command into a bitmap, presumably as high as your print head 
andas wide as your paper. Then you will have to store the bitmap 
somewhere, or print it directly. The standard ImageWriter driver 
provides two methods of doing this. In draft mode printing, 
bitmaps are printed immediately. In spool printing, all Quick- 
Draw calls between PrOpenPage and PrClosePage are stored in 
a QuickDraw picture, which is kept in a special file for this 
purpose. A number of pages are buffered up in the Print File, then 
the routine PrPicFile is called to print them out. There is nothing 
mysterious about this, but the translation process from Quick- 
Draw calls to dot-matrix printer commands may mean some 
work! 

Irecommend starting with the simplest method of graphics 
printing, then working up. If you want to implement graphics 
printing on your printer, then make the “command-shift-4” 
routine in the driver work first. Get a copy of the QuickDraw 
manual and a copy of the Printer manual, go to a quiet place, and 
work out the tranlsation algorithm from screenBits to paper. The 
feeling of accomplishment you get will be a tremendous boost! 

PrOpenPage is called to clear out the printing port and make 
it ready for the next page. All variables associated with your 
printing port should be returned to the initial state. Anything 
appropriate for the printer at top of page should be done here. 
PrOpenPage also makes the printing port the current port, al- 
though not all applications need this feature. 

PrClosePage is called when the application is finished with 
printing the current page in the document. My method of printing 
waits until PrClosePage is called, then prints out the whole page 
at once. This method is appropriate for text-only printing, but 
may not be for other methods, especially if memory is tight. 
Between PrOpenPage and PrClosePage, I store text in a dynami- 
cally allocated array of structures called “line”s. I use an integer 
to flag whether the line actually has text in it, and acharacterarray 
to hold the text. If I handle up to 66 lines on a page, and 164 
characters in a line, then it takes my code 11 kilobytes to hold the 
array of lines. If we wish to handle multiple styles (italic, 
underline, etc.) then we could modify the line structure to hold 
style information as well without increasing the size of the array 
of lines very much. For graphics printing, this method is 
probably not appropriate because of the large amount of memory 
that would be needed to hold bitmaps. 

Here is the algorithm used in MyPrClosePage to actually 
print the text. I obtain a pointer to the driver’s global storage, 
where I have stashed information about the current print job’s 
parameters. From the prJob.iFstPage and prJob.iLstPage fields, 
I determine whether the current page is within the range of lines 
which get printed. If the current page is before the first page to 
be printed, MyPrClosePage returns without doing anything 
except incrementing the page counter. If current page is after the 
last page, I stuff an error code іп PrintErr. (I don’t know whether 
this is the standard way to stop printing at this point, but it seems 
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to work.) Then I cause the user’s “end-of-file” string to be sent 
to the printer. After checking the page range, I begin the process 
of printing out the lines in the output buffer. 

Actual printing is implemented by calling the driver’s con- 
trol routine with acsCode = iPrIOCt, [Param 1 = the pointer to the 
base of the current line's text array, and IParam2 = the number of 
bytes to print. End of line is handled by calling the driver's 
control routine with the appropriate code for end of line. For each 
line in the buffer: 

Call the pIdleProc procedure of the current print record. 

If PrintErr is equal to iPrAbort then return. 

Else 

Check the flag to see if the line has text in it. 

Find out how many characters (index of last non-space 
character +1) 

Call the driver to print the text. 

If at end of page, then 
Call the driver to do a form feed. 

Else 
Call the driver to advance the paper. 


Calling the driver's control routine to print the text is only 
one method. It is also possible to send the textto the serial driver 
directly from the printing code, or use any other method you can 
think of here. 

PrCloseDoc is used to dispose of a printing port, and to 
signal to the printing code that the current print job is finished. 
Any storage which has been allocated for printing is disposed of 
here, and the port is closed. The TPrPort must be closed prior to 
disposing of the port, or the memory allocated by the visRgn and 
clipRgn will not be reclaimed. If the printing port storage was 
allocated by the printing code, dispose of it here. Don't dispose 
of storage which belongs to the application! 

Part 5: PrPicFile 

The PDEF 5 overlay contains the routine PrPicFile. The file 
"PDEFS.c" merely shows the proper header to use, and the 
parameters passed to this routine. When spool printing, the 
printing code stores all drawing commands passed to it in a disk 
file. The routine PrPicFile is called by the application after the 
print job has been stashed away in the picture file. PrPicFile then 
prints the file. Recommended procedure is to swap as much of 
the application out of RAM as possible, then call PrPicFile. This 
means that if you choose to implement spool printing, then you 
canuse lots and lots of RAM when youare actually printing. You 
may need lots and lots of RAM to translate a QuickDraw picture 
to a nice looking dot matrix output page. 

I am glad I didn't have to implement spool printing for the 
purposes of this article, but I certainly wish everyone the best of 
luck. 

Part 6: Installation, or Talking to the user 

The Chooser desk accessory provides a standardized inter- 
face for new device drivers to obtain configuration information 
from the user. This means there is no need to provide a 
configuration program in order to be able to handle multiple 
device types. When a device icon is selected in the Chooser 
dialog, the Chooser looks in the device resource file for a 
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resource of type ‘PACK’, ID -4096. This resource has the 
“standard” header for stand alone code resources as implemented 
by LightspeedC and as documented in the Device Manager 
chapter of Inside Macintosh Volume 4. That chapter is recom- 
mended reading for what follows. 
The format of the ‘PACK’ resource header is as follows: 

Offset (hex) Word 
short branch to offset 0x10 
Device ID (word) 
'PACK' (long word) 
0хҒ000 (-4096) 
Version word 
Flags (long word) 
0 Start of code 


“=O PORNO 


LightspeedC formats this resource header correctly, but 
provides no way to set the version and flags. A separate utility 
program is provided to show how to set these. My resource has 
a version number of 1, and uses the Chooser right button. I do not 
use the List Manager here, but provide a string for the Chooser 
to label the list when choosing my device file. When my icon is 
selected in the Chooser, this string appears as a label to tell the 
user that more configuration options are possible. Setting the 
flags to the proper value tells the Chooser that I will use the right 
button, and ‘STR ‘ number -4092 gives it a button title to use: 
“Setup...”. The Chooser communicates with my ‘PACK’ re- 
source as if it were the following Pascal function: 


FUNCTION DeviceCmessage, caller: INTEGER; objName,zoneName: 
StringPtr; p1,p2: LONGINT) :OSErr; 


I declare the function in C as: 


pascal OSErr mein(message, caller ,objneme, 
int message, caller; 

StringPtr objname, zonename ; 

long р1,р2; 


хезер 


Theonly field which is of interest to me here is the integer 
message, and only when that is equal to the constant buttonMsg 
(19). When called with the button message, the РАСК’ resource 
puts up a dialog box, and gives the user a set of configuration 
options. The baud rate can be set here, as can flow control. I 
provide five editText items for the user to enter printer control 
strings. Most, but not all, printers will produce a carriage return 
and then a line feed when they receive the string: “Ап” or "^M^J" 
or a decimal 13 followed by a decimal 10. Using the second 
notation, I let the user edit these strings so that his printer can be 
used. Forexample, with my Tandy DMP-110, one uses “4M” for 
end-of-line, “АГ” for end-of-page, and there are several choices 
for the string for initializing the printer. I also provide at this ime 
strings for top-of-page and end-of-job, although I usually don't 
use either with my printers. 

Another way to handle this would be to provide several 
configuration files, with the same creator type as your Printer 
Resource File. The Chooser maintains a list box for use by device 
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packages; you have probably seen it in use if you have chosen a 
LaserWriter or used AppleShare. The list box could be used to 
select between configuration files in the same manner that the 
LaserWriter driver selects between devices on the AppleTalk 
network. Details of how to do this can be found in ІМ4. 

When my device package is called, I get the user's choices 
via ModalDialog, and store the results in the printer resource file 
if the "Save" button is hit. The Printer Resource File is always 
the last-opened resource file when the package is called by the 
Chooser, so my configuration resources are always right at hand. 
I use an array of integers to store configuration information, and 
astring listto store the printer control strings. When changing the 
string list, make sure to resize the Handle to the resource in case 
the user has entered longer or shorter strings than were there 
before. 

There is one problem here. When the device package is 
chosen, it may be because the user wants to change some of my 
configurations, and not to change printers at all. My driver will 
not load a new set of settings, however, until its open routine is 
called. This may cause some delay in realizing the effects of 
changing the settings from the Chooser, particularly if an appli- 
cation calls PrOpen only once, which many older applications 
do. 

Part 7: Nuts and bolts, or Putting it all together 

The Daisy printer Resource File requires six LightspeedC 
project files, seven resource files in addition to the Printer File, 
and ten source files to create. Because of the environment used 
by LightspeedC, there is no Makefile, so you will have to follow 
instructions here in order to get it right. (This task will be much 
easier with a “batch” oriented development system.) 

Files used to create the Daisy Printer Resource File: (All 
files are contained on disk “src” and in folder “Printer”, available 
on the source code disk for this issue of MacTutor. See the 
MacTutor Mail Order Store page for details on obtaining this 
disk.) See Table 1. 

Note: You must obtain the SysEnvirons glue and header file 
for your development system, also. 

LightspeedC is an excellent choice for a development sys- 
tem, but there are things which it will not do. It will not allow you 
to produce the correct headers for the PDEF resources, for 
instance, because it uses a standard code resource header. I get 
around this limitation by hacking the code resources after Light- 
speedC is finished with them. Prior to the offset table at the 
beginning of each of these resources, I put an illegal instruction 
(Ox4afc). A utility program I wrote reads in the code resource, 
strips off everything up to and including the illegal instruction, 
and writes out the modified code resource to its file. Doing things 
this way imposes certain restrictions on what you put in the code. 
Specifically, you cannot have anything in the PDEF code which 
will cause LightspeedC to insert code in front of your main() 
function. Things I know of which will cause this to happen are: 


Linking libraries before the main code. 
Switch statements. 


The PDEF resources must not have switch statements when 
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using LightspeedC. Any libraries used in them must have names 
which are lexically greater than your printing code. Name the 
printing code source file "AAA whatever.c" to accomplish this, 
or perhaps name the library file "ZZZlib.lib". These restrictions 
of course do not apply to other development systems, which may, 
however, impose other ones. 

The PACK resource and the DRVR both require flags to be 
set in their headers. The PACK resource must have flags to tell 
the Chooser what its capabilities are, and the DRVR must 
respond to the correct subset of driver calls. My utility program 
sets the flags correctly for the PACK resource and the DRVR. 

What follows is a detailed description of how to make the 
printer resource file using LightspeedC and RMaker. Too bad 
there is no “make” utility for LightspeedC! Instructions for other 
development systems may be more or less similar to these. 
Change to suit your disk/machine/development system configu- 
ration. 

Obtain a 512ke or better Mac. Create a system disk named 
"bin", with LightspeedC and a folder of “#include” files on it. 
Call the system folder “sys”. Create another disk named “src” 
with a folder named “Printer” on it. Put the printer driver sources 
in this folder. Boot from “bin” and put “src” in the other disk 
drive. 

Make a project for the driver. Set the project type to “Device 
Driver", number 2, name *.XPrint". Use the “Add...” item under 


File nameTypeCreatorWhat 


LightspeedC “Project” files: 


DRVR_proj PROJ KAHL 
PACK_proj PROJ КАН. 
PDEF®_proj PROJ KAHL 
PDEF4.proj PROJ KAHL 
PDEF5_proj PROJ KAHL 
UTILS.proj PROJ KAHL 


Driver project 

Chooser interface project 
Draft printing code project 
Dialog code project 
PrPicFile project 

Utility programs project 


resource files: 


DaisyDRVR 292 999 
DaisyPACK 777 929??? 
DaisyPDEF® ???? 2??? 
DaisyPDEF4  ???? 297? 
DaisyPDEF5 ???? 7777 
DaisyPREC® 27777 2777? 
dialogs.rsrc 2222 727? 


‘DRVR’ -8192, ‘DATA’ -16320 
‘PACK’ -4096 

'pdef^ Ø -> ‘PDEF’ Ø 

'pdef^ 4 -> ‘PDEF’ 4 

'pdef^ 5 -> 'PDEF' 5 

‘PREC’ 0 

resources created by RMaker 


Daisy 2???  ???? The final actual printer resource file! 
text files: 
Daisy.r TEXT KAHL RMaker source to put it all together 


dialogs.r TEXT KAHL 
mkDefault.c TEXT КАН 


РАСК. с ТЕХТ KAHL Chooser device interface code 

PDEFS .c TEXT KAHL Draft printing code 

PDEF4 .c TEXT KAHL Dialog code 

PDEF5.c TEXT KAHL  PrPicFile stub code 

prglobals.h ТЕХТ KAHL Daisy header file, included in all sources 
Utils.c TEXT KAHL Utility program to reformat code headers 


XPrint.c TEXT KAHL Driver code 
Application files: 


Code Fixer compiled Utils project 
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RMeker source to resources created by ЁМакег 
C code to create default Print Record 


the "Source" menu to add “XPrint.c” and “Environs.lib”. When 
you choose the “Build Device Driver" menu item, LightspeedC 
will create a file which contains ‘DRVR’ #2 and ‘DATA’ #- 
16320. The RMaker command file converts the driver to 
‘DRVR’ #-8192, named “.XPrint” before installing it in the 
Printer Resource File. The ‘DATA’ resource is converted to 
‘PREC’ Я-8192. (The driver file created by LightspeedC is to be 
placed in the folder “src:Printer” if you wish to use the RMaker 
command file and utility program without modification.) The 
driver file is named "DaisyDRVR". 

Make a project for the Chooser device interface. Project 
type is “code resource", type ‘PACK’, ID -4096. Add the 
“PACK.c” source to it and create the code resource, placing it in 
the file “DaisyP ACK”. 

Make a project for each of the ‘PDEF’ resources. Set the 
project type to “code resource", type ‘pdef’, ID number from the 
source file name. (The utility program converts *pdef' to ‘PDEF’ 
when it reformats the code.) Create the three resource files 
shown. Example: PDEFO.c is used in PDEFO proj to create 
DaisyPDEFO, containing “рде? 0. Later, the utility program 
reformats the header and converts it to ‘PDEF’ 0. And so on. 
(Please, Father, buy me a hard disk and MPW C.) 

Create an empty resource file in the “Printer” folder named 
DaisyPRECO. You can use the LightspeedC editor to create an 
empty text file for this purpose, since LightspeedC text files have 
resource forks. Just create the text file, and set the tabs in it, so 
LightspeedC creates an ‘ETAB’ resource. Alternately, use 
RedEdit. The utility program puts the default Print Record in this 
file, but does not have the ability to create the file by itself. 

Create a LightspeedC project file for the utility program, 
“Utls.c”. Type is Application, name is whatever you like. Add 
the source file “Utils.c” and select "Run..." from the “Project” 
menu. There is no need to create the application, unless you want 
to use it under MultiFinder. When you run Utils.c, it will set all 
the flags properly in the ‘DRVR’ and ‘PACK’ resources, refor- 
mat the *PDEF' code resources, and create a default Print Record, 
‘PREC’ 0. 

Run RMaker. Compile "dialogs.r" to create the dialogs, 
strings, string list, and private resource types. RMaker will create 
"src:Printer:dialogs.rsrc" at this point. Compile 
"Daisy.r'. RMaker gathers together all the re- 
sources for the Printer Resource File, and creates 
"bin:sys:Daisy". Edit the RMaker source files if 
your pathnames differ or if you want to change any 
of the dialogs or other resources. Place Daisy in your 
system folder. 

Run the Chooser desk accessory to install the 
driver in the system file, and to set any options which 
appear in your Chooser interface dialog. Chooser 
may not want to fetch the new ‘DRVR’ resource 
from your Printer Resource File if Daisy is your only 
Printer Resource File. (Chooser is meant for the end 
user, who usually does not compile new printer 
drivers several times a day.) It may be necessary to 
have two Printer Resource Files during the develop- 
ment stages. When you create a new Printer Driver, 
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first install the extra Printer File, then re-install Daisy. Do this 
justto make sure the Chooser clears out the old copy of the driver 
for you. Do not attempt to use RMaker to install the new driver 
in the system file (I tried this once). The Printer Resource File is 
installed on other system disks by copying it into the system 
folder, just as you would install an ImageWriter or a LaserWriter 
printer driver. 
Part 8: What else, how to find out more. 

Much of the information I needed to make my Printer 
Resource File work was buried in the depths of the Printer 
Manager Chapter of the Promotional Edition of Inside Macin- 
tosh. This is the copy that looks like a Manhattan phone book. 
The Chooser device interface information is found in the Device 
Manager Chapter of Inside Macintosh 4. In order to use the 
Chooser interface in a more advanced fashion, it will be neces- 
sary to learn how to use the List Manager, also in Inside 
Macintosh 4. The secrets of the Print dialogs were revealed in 
Macintosh Technical Note 4/95. There is a new low-level printer 
call, PrGeneral, whose calling sequence is given in Technical 
Note #128. This routine is found in 'PDEF' #7, I believe, and the 
resource apparently has a standard header (like the ‘PACK’ - 
4096 resource). 

As you may know, Macintosh Technical Support is pretty 
sparse on documentation for writing a Printer Resource File. The 
following features of the printer interface were incorrectly or 
incompletely documented in my Macintosh documentation. 
More may be found. 

° The driver’s Font Manager control call is passed a 

pointer to an FMInput, and not an FMOutput, record. 

° Some applications require PrOpenPage to do a SetPort 
tothe Printing Port, while mostdo not. My PrOpenPage 
documentation does not mention this. 

о Тһе numer and denom parameters to StdText аге 
Points, and not integers. (Perhaps it is time to retire the 
“РһопеВоок”.) 

PrintVars: What are they, and how тау we use them? 

Nevertheless, Apple has released all (or most of) the infor- 
mation that is necessary to define the specifications for a Printer 
Resource File, and they have told application developers “This is 
how the sucker is called." Without commenting on the prettiness 
(orlack thereof) of the Printer Manager interface, one can say that 
this interface will not change (much) in the near future, unless 
Apple is ready to break every application which prints on the 
Macintosh. For good or ill, then, if you want to write a Printer 
Resource File, you have to do it (mostly) this way. 

Daisy was compiled on a 512ke with 1 Meg of RAM 
installed and an external 800k disk drive. The LightspeedC 
compiler version 2.11, System 4.1, Finders 5.5 and 6.0b3, 
Chooser 3.1, and some version of RMaker were used to produce 
it. The WriteNow word processor was used to test it. The 
following applications were known to be able to print with it as 
of September 28, 1987: 

DarTerminal 3.2 (Dartmouth AppleTalk emulator) 
Finder 5.5, 6.063 (Print catalog) 

MockWrite 4.3 desk accessory 

LightspeedC 2.11 
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о 


MacTerminal 2.2 
MacWrite 4.5,4.6 
MDS Edit 2.0 d1 
Microsoft Word 1.05 
Microsoft Word 3.01 
Pretty Print 
Teach Text 
WriteNow 1.00 
This is a real bonus for me, since I was only trying to get 
something to work with WriteNow! The structure of the Printer 
Resource File is complicated, the interface is hard to understand, 
and the number of example programs is now exactly one, but the 
Macintosh Printer Manager fulfills its primary objectives: It is 
Device Independent, and works with all (properly written) 
Macintosh applications. 
I would like to thank David Oster, who insisted that it would 
be possible to write one of these things with the existing docu- 
mentation. David, you were right! 


j PACK.proj  Deisyr баю” — mkDefault.o 


шй uiu 
ES 


PDEFO_proj PDEF4 proj РАСК о 


Fig. 6 All the files required to bulld a printer resource file 
Control Key Codes 

Control characters are sent to the printer by entering “АМ” 
in the dialog box. This would send a “control-M” to the printer, 
which is an ascii 13 or a carriage return. Here are the control 
characters on the Mac II extended keyboard. The first column 
gives the control-key sequence as you would type it, the second 
column gives the decimal ascii character generated, the third 
column gives the ascii code name, and the last column gives an 
alternative control-key sequence on the extended keyboard. Use 
this table to figure out the printer control strings needed to make 
the printer operate properly. There does not appear to be any 
printable character that would generate ascii codes 0, 30 and 31 
when used with the control key on this keyboard. This is a serious 
problem when using this driver with the imagewriter II, since 
some of it's programming requires the NULL character and there 
is no way to generate this. The apple (command) key in combi- 
nation with the tilde С) key does produce ascii 0, but this is not 
a printable combination so can't be used in our set-up dialog. 
Normally control-@ produces ascii 0 on normal keyboards, but 
on the Apple keyboard it does not! Note thatall the function keys 
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return the same ascii value! The option, apple and shift keys do 
not generate a code. A simple Basic program generated this table, 


as shown below: 
REM This program finds control codes 
CLS 


PRINT “enter your control character...” 


key: 
key$=INKEY$ 
IF key$-"^ THEN GOTO key 
PRINT “The ascii code is “;ASCCkey$) 
GOTO key 


CONTROL- ASCII NAME OTHER KEY 


A 1 SOH HOME 

B 2 STX 

C 3 ETX ENTER 

D 4 EOT END 

E 5 ЕМО НЕГР 

F 6 ACK 

6 7 BEL 

H 8 BS DELETE 

I 9 HT TAB 

J 10 LF 

K 11 VT PAGE UP 

L 12 FF PAGE DOWN 

M I3 CR RETURN 

N 14 S0 

0 15 SI 

P 16 DLE F1-F15 

Q 17 DC1 

R 18 DC2 

$ 19 DC3 

T 20 DC4 

U 21 NAK 

V 22 SYN 

W 23 ETB 

X 24 CAN 

Y 25 EM 

Z 26 SUB 

[ 27 ESC ESCAPE 

A 28 FS L. ARROW 

] 29 65 R. ARROW 
30 RS U. ARROW 
31 US D. ARROW 

SPACE 32 SPACE 


/* 


* LS C source for PDEF 8, to implement draft mode printing 


* on а serial device. 

* Eerle R. Horton, September 19, 1987. 
* All rights reserved. 

*/ 


®include *prglobals.h"^ 
®include «EventMgr .h» 


pascal TPPrPort myPrOpenDocC); 


pascal void myPrC loseDoc(); 
pascal void myPrOpenPage( ); 
pascal void myPrC losePage( ); 
pascal void nyStdTextC); 
pescal int nyStdTextMeas(); 
void myC learPage(); 
Ptr ellocete(C); 

void free(); 

void bcopy(); 
DPstorage DrvrStorage(); 
void checkabort(); 
maint) ( 
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аза ( 
dc.w ILLEGAL 3, So I cen find it... 


jmp nyPrOpenDoc 
jmp myPrCloseDoc 
jmp myPrOpenPage 
jmp myPrClosePage 
) 
) 
/* 


This function is supposed to return a pointer to а special- 
ized GrafPort Са TPrPort) customized for printing. Due to the 
paucity of documentation on how to go about this, I do not 
know whether I am going about this in exactly the right way, 
but I sure hope so. I set portBits.bounds for the port to the 
empty Rect (0,0,0,0) and then install the stendard QuickDrew 
routines as GrafProcs. In place of StdText, I put my own 
StdText routine. Hopefully, QuickDrew will keep track of the 
correct pen location for me, and call my routine whenever it 
is necessary to drew text. I just put the text in a big 
buffer for now, and then print it out when I get called to 
close the current page. This takes up some memory, but solves 
the problem of what to do when the application wants a reverse 
line feed. 

Other tasks: save а copy of the user print record for later 
use in formetting the output page; save а copy of the user 
print record in the printer resource f ile 

x/ 


pascal TPPrPort myPrOpenDocChPr int, pPrPort,pIOBuf ) 
THPrint — hPrint; 

TPPrPort pPrPort; 

Ptr — pIOBuf; 


TPPrPort thisport; 
pline thepage; 
Handle us; 

register DPstoragedsp; 
THPrint — savePrint; 
РгРагап %рб; 


us = CHandle)(GetResource( 'PDEF ^ ,0)); 
asm { 

move. ]us,ad 

HLock 


/* Assign storage for printing port end page buffer. */ 


oo = (plinedal locate(Clong )CNROWS*sizeof Cline)))) 
== nil) 

PrintErr = iMemFullErr; 

return nil; 


else if(pPrPort == nil)( 
ifCCthisport = CTPPrPort) 
elloceteCClong2?sizeof (TPrPort))) == nil){ 
free(thepage); 
PrintErr = iMemFullErr; 
return(ni1); 


) 
thisport->fOurPtr = TRUE; 


else ( 
thisport = pPrPort; 
thisport-»fOurPtr = FALSE; 


/* Copy print record into private storage area. */ 
dsp = DrvrStorageC; 
pb = &dsp->prpb; 
dsp->Print = **hPrint; 
thisport-) 1GParam4 = Clong)thepage; 
dsp-)Print.prvob.bUDocLoop = bDraf tLoop; 
OpenPort( thisport); 

/* Fill out gProcs for this port. */ 
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SetStdProcs(&thisport-?gProcs); 
thisport-?gProcs.textProc = CQDPtromyStdText; 
thisport- gProcs.txMeasProc = CQDPtrOmgStdTextMeos; 


thisport-?gPort.grafProcs = &thisport-»gProcs; 
x 


* Set up the port Rect in the proper coordinates, relative to 


the page 
* and to the paper. 
%/ 
thisport-»gPort.device = dsp-»Print.prinfo. iDev; 
thisport-?gPort.portRect = dsp-Print.prInfo.rPege; 
thisport-»gPort .portBits.bounds.top = 
thisport->gPort .portBits.bounds. left = 
thisport-»gPort.portBits.bounds .bottom 
thisport-»gPort .portBits.bounds.right = 


пи 
сә 
we 


SetPortCthisport); 
/* Offset the page (portRect) relative to the paper. */ 
Por tSizeCdsp->Pr int .prInfo.rPage.right,dsp- 
)Print.prInfo.rPege.bottom); 
MovePortToC- dsp->Print.rPaper. left, - dsp- 
»Print.rPaper. top); 
GrafDeviceCdsp-)Pr int .prInfo.iDev); 
myC learPage( thepage ); 
pb->csCode = iPrDevCt!; 
pb-) Param! = lPrReset; 
esn( 
move. 1pb,ad 
PBControl 


/* Init the printer. */ 
/* Driver code does work. */ 


dsp-?pagenum = 1; 
ifCdsp->Print .prJob.pIdleProc == nil) 
dsp-?Print.prJob.pIdleProc = (ProcPtr )checkabor t; 
savePrint = CTHPrint)GetResource( ‘PREC’, 1); 
if(savePrint != nil)( 
LoadResource(savePr int); 
*XsavePrint = dsp- Print; 
ChangedResource(savePr int); 
Re leaseResource(savePr int); 
) /* Determine proper mergins. */ 
dsp->nlines = (dsp-»Print.rPaper .bottom - dsp- 
»Print .rPaper . top) /CHARHEIGHT ; 
return(thisport); 


pascal void myPrCloseDoc(pPrPort) 
eee pPrPort; 


pline thepage ; 
Pfg settings; 


freeCpPrPort-> 1GParan4 ); 
ClosePort(pPrPor t); 
) ifCpPrPort->fOurPtr) freeCpPrPort?; 
/* 
* This routine opens а new page. Actually, all it does is 


clear out the array of lines in preparation for more fun with 


QuickDrew. I suppose it could also send a reset command to 
the driver... 
x/ 
pascal void myPrOpenPage(pPrPort,pPageFreme) 
TPPrPort pPrPort; 
TPRect pPegeFrame; 


register DPstorage dsp; 
dsp = OrvrStorage(); 
if(pPegeFreme != nil) 
*pPageFreme = dsp-)Print.prinfo.rPage; 
SetPor t(pPrPort); 


myC learPage(pPrPor t-> 1GParam4 ); 
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/* 

* This is the routine which does the actual printing. 
QuickDraw calls which have called our StdText substitute 
routine have filled up a buffer with lines of text. Now, we 
just get the buffer and print it. 

x 


pascal void myPrClosePage(pPrPor t) 
co pPrPort; 


register DPstorage dsp; 
register pline theline; 
register int i, iocount; 
PrPeren *pb; 


dsp = DrvrStorage(); 

pb = &dsp—prpb; 

if Cdsp-?pagenum < dsp-)Print.pruob. iFstPage ) ( 
dsp-?pagenum**; 
return; 


if (dsp-»pagenumt++ > dsp-Print.prJob. iLstPage) ( 
PrintErr = iPrAbort; 
if Cdsp-»preofstr(O] != 407 
pb->csCode = iPrIOCt!; 
pb-> lParam! = Clong)(&dsp-> preofstr[ 11); 
pb-?lParem2 = Clong2dsp- preofstr[2]; 
asm ( 
move. 1pb,e 
PBControl 


) 


return; 


if dsp-»Print.prStl.feed != feedCut || waitnextpage()){ 
theline = Ср1іле ”рРгРогі-› 1GParam4; 
if Cdsp->»prtopstr[@] != 447 
pb-?csCode = iPrI0Ctl; 
pb-) 1Рагаті = Clong)(&dsp-> prtopstr[1)); 
ро-› 1Param2 = (long)dsp-> pr topstr [8]; 
esn( 
тоуе.1рЫ,а0 
PBControl 


) 
forCiz0;dspnlines - i; i++)( 
(* dsp->Print .prJob .pIdleProc2C); 
if(PrintErr == iPrAbortOreturn; 
ifCCtheline*iD)- dirty == DIRTYO( 
iocount = WIDTH; 
whileC Ctheline*i)- text[-iocount] == * *5() 
++jocount; 
pb->csCode = iPrIOCt1; 
pb-> Parami = 
Clong)(&Ctheline+i)->text[0]); 
ро-› 1Param2 = (long)iocount; 
asm ( 
nove.1pb,e 
PBControl 


) 

pb-?csCode = iPrDevCt!; 

ifCi < dsp5nlines - 1) 
pb-?lParami = lPrLineFeed; 

else рЫ-›1Рагат1 = 1РгРадеЕпа; 


esn 
nove.1pb, a8 
PBContro] 
) 
) 
else PrintErr = iPrAbort; 


/* 
* All text drawing calls in the TPrPort get sent here. Find 
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the current pen location end translate it to row and colum of 
the page buffer, squirt the text into the buffer. 
*/ 


pascal void myStdTextCbyteCount, textBuf ,numer , denom) 
intbyteCount ; 

QDPtr textBuf ; 

Pi numer ‚бегом; 


Point thepoint; 

TPPrPort tp; 

pline thepage; 

int width; 

intx,y; 
GetPort(C&tp); 
ifCtp-»gPort.device == IDEV19) width = 7; 
else if(€tp->»gPort.device == IDEV15) width = 5; 
else width = 6; 
thepage = (pline)tp-> 16Рагат4; 
GetPenC&thepo int); 
/* (Local is page, Global is paper.) */ 
LocalToGlobal(&thepoint); 
х = thepoint.h/width; 
y = thepoint.v/CHARHEIGHT; 
bcopy( tex tBuf ,& CC thepagety)-> text [x 12), byteCount); 
Cthepagety)->dirty = DIRTY; 
Move(width*byteCount, 0); 


pascal intmyStdTextMeas(byteCount, textBuf , numer , denom, info) 
intbyteCount; 

Q0Ptr textBuf; 

Point *numer, *депом; 

FontInfo *info; 


TPPrPort tp; 
GetPor t(&tp); 
if(tp->gPort.device == IDEV18)info->widMax = 7; 
else if(tp->gPort.device == IDEV15)info->widMax = 5; 
else info->widMax = 6; 
info-»ascent = 9; 
info-?descent = 2; 
info-? leading = 0; 
numer->v = denom->v = 1; 
denom—>h = 6; 
numer-?h = info-)widMax; 
return Cinfo->widMax * byteCount); 


) 
void myClearPage(thel ine) 
pline theline; 


intcount; 
unsigned char*ch; 


count = NROWS; 
Clear: 

theline dirty = “DIRTY; 

ch = &thel ine-> text [2]; 

asm 
move.1]ch,ad 
move .w®(CWIDTH/4)-1),d@ 
тоуе.180х20202020,41 


loop: 
move.1d1,Ca0)* 
дога 40,61оор 
ifC-counto( 
theline**; 
goto clear; 


Ptr allocate(size) 
es size; 


esn( 
move. 1512е, 40 
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NewPtr 
nove.1689,d0 j; LightspeedC returns function 
/* value in dð. */ 


) 
void Тгее(ріг) 
Cee 


asm ( 
move. ]ptr, ad 
DisposPtr 


) 

/* 

* А UNIXism. Want to make something of it? 
x/ 

void bcopy(src,dst, count) 

unsigned char *src,*dst; 

int count; 


esn( 
move. 1ѕгс ад 
move. ]dst,al 
с1г.1 dé 
move .wcount, 40 
BlockMove 


) 
) 
"def ine UTableBase 284 
x 


* This function returns a pointer to the printer driver’s 
private 

* storage. We don’t need to lock the Handle, since it is 
always locked 

* when the driver is open. 

x 


DPstorage DrvrStorage( ) 


DCtlHendleourDCtlEntry; 
DHstorege ourdCtiStorege; 


esn( 
move #2,40 
851.1 82,40 3, dø = BL 
move. 1UTableBase, að j; 90 -> base of unit table 
adda 40,20 j; 80 -> second entry 


nove. 1 (að), ourDCtlEntry ;; handle to DCtlEntry(2] 


) 
ourdCtiStorage = CDHstorage)C*ourDCtlEntry2-»dCtlStorage; 
return(*ourdCt 1Storage ); 


/* 

х Abort printing if command '.^ pressed. 
af | 

void checkabor t( ) 


EventRecord myevent; 
int c; 
if (GetNextEvent(keyDownMask, &myevent))( 
if CLoWord(myevent.message & charCodeMask) == '.' && 
Cmyevent.modifiers & cmdKey) 2( 
PrintErr = iPrAbort; 


) 
) 
/* 
* Modal dialog box: “Insert next sheet.” 
х/ 


аи 


DialogPtr sheetdialog; 
WindowPtr tempport; 
int itemhit, donetype; 
Handle doneitem; 
Rect donebox; 
if (Csheetdialog = GetNewDialogCSHEETDIALOG, OL, CWindowPtr) 
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-1)) == nil) 
return FALSE; 

InitCursor(); 
GetDI tem(sheetdialog, DONEITEM, &donetype, &done i tem, &donebox ); 
GetPor t(& temppor t); 
SetPor t(sheetdialog); 
PenSize(3,3); 
InsetRect (&donebox, -4, -4); 
FrameRoundRect(&donebox, 16, 16); 
Moda lDialog(@L, &itemhit); 
DisposDialog(sheetdialog); 
SetPor tC temppor t); 
ifCitemhit == STOPITEM) return FALSE; 
return TRUE; 


/* 

х PDEF4.c. 

x 

* Generic daisy/dot matrix text printer driver 


* Earle R. Horton August 31, 1987 
* All rights reserved. 
x 


x This module contains the code for validating, creat- 
ing 

* апа modifying print records. 

x 

jl 


* This module is to be placed into a code resource project 
using LightspeedC, version 2.01 or greater. Тһе project is to 
be made into PDEF resource number 4. А11 of the code up to 
and including the first illegal instruction is to be stripped 
off, so that the PDEF will have the standard format for 
resources of this type. Switch statements cannot be used, 
since LightspeedC compiles them into separate code which is 
edded to the beginning of the code resource, before our 
standard header. I do not know at this point which types of 
flow control constructs are safe, but I have determined by 
disassembly that the following will produce useable code: 

x if, if/else blocks 

x gotos 

x 


* Instructions, or “How I did it.” Create from this module & 
code resource of type ‘pdef’ ID 4. Run the program utils.c to 
make it into PDEF ID 4 and to strip off the standard header. 

*/ 


#include «DialogMgr.h? 

* include «EventMgr .h? 

include “prglobals.h” 

"def ine STYLEDIALOGCOxE200) 

def ine JOBDIALOG (0хЕ001) 

"define XTRA 24 /* Six extra longs for our use. */ 
def ine DLGSIZE CClongXXsizeofCTPrDlg) + XTRA)) 
define X TPSIZECClongX(sizeof CTPrint22) 

/* Items we handle in the job end style dialogs. */ 
"def ine CANCELITEM 2 


define СРІ 10В0ТТОМ 4 
define СРІ 12В0ТТОМ 5 
"define CPIISBUTTON 6 
define — STRAIGHTUPITEM 7 
define — SIDEWAYSITEM8 
define — ALLBUTTON5 
define | RANGEBUTTON 6 
"define | FROMNUM 1 
"define ТОМОМ 9 
"define COPIES 11 
define X FANBUTTON 13 
define SHEETBUTTON 14 


pascal void MyPrintDefault(); /* Fill default print record*/ 
pascal Boolean MyPrStiDialog();  /* printer style dialog. */ 
pascal Boolean MyPrJobDialog();  /* printer job dialog. */ 
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pascal ТРРг019 MyPrStlInitC); 
pascal ТРРг019 MyPrJobInit(C); 
pascal Boolean MyPrDigMain(); 
pascal Boolean MyPrValideteC); 
pascal void МуРгЈобМегдес );- 
pascal Boolean MyFilter(); 
pascal void HendleStyleItemsC); 
pascal void HandleJobItems(); 
TPPrD 1g TPPrD1gal locate( ); 
void pushradiobut ton); 
int NumToString(),StringToNum(); 
Boolean Valid(); 

void mkDefault(); 

void freeC); 

mainC) 


/* Set up style dialog. */ 
/* Set up job dialog. */ 

/* Print dialog supervisor*/ 
/* Validate print record. */ 
/* Copy а job subrecord. */ 
/* Filter dialog events. */ 
/* Handle Style Items. */ 

/* Handle Job Items. */ 


esn( 
dc.w ILLEGAL Me 
jmp MyPr intDefault 
jmp MyPrSt1Dialog 
jmp MyPrJobDialog 
jnoMyPrStlInit 
jmp MyPrJob Init 
jmp MyPrD1gMain 
jmp MyPr Validate 
jmp MyPr JobMerge 


So I can find it... 


) 
) 
/* 

* This function fills & print record with defaults. The 
default values are stored in the Printer resource file, in 
PREC 0. This is easy. Then we check the fields of the print 
record for anything obviously illegal. If the default print 
record contains stuff that is bad, then we correct it and 
update the copy in the printer resource file. This should 
never happen, but some wise guy with a copy of ResEdit and 
eus breins then sense may think he knows more then we do. 
pascal void MyPrintDefeultChPrint) 

THPrint hPrint; 


( 
THPrint — thedefault; 
thedefault = CTHPrint )(GetResource( ‘PREC’ ,022; 
if Cthedefault == nil){ 
mkDefaultChPrint); 


else ( 
LoadResource( thedefault); 
if(MyPrValidate(thedefault)) ( 
ChangedResource( thedef aul 10; 
Wri teResource( thedefault); 


**hPrint = **thedefault; /* What the hell. */ 


) 
pascal Boolean MyPrStIDialogChPrint) /*print style dialog. */ 
THPrint hPrint; 


returnCMyPrD1gMainChPrint,MyPrStlInit22; 
pascal Boolean MyPrJobDialogChPrint) /* Conduct printer job 
dialog. */ 
THPrint hPrint; 


returnCMyPrD1gMainChPrint,MyPrJobInit22; 


/* 
* The style dialog initializer. 
x 


pascal ТРРгО1а MyPrStlInitChPrint) 
THPrint hPrint; 


TPPrDig фр; 
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tp = TPPrDigallocate(); 
(Ge tNewDialog(STYLEDIALOG, tp,- 1); 
if(C*hPrint)->prinfo.iDev == IDEV 10) 
pushrediobutton tp, CPI IBUTTON, CPI 1@BUTTON, CPI 1ISBUTTON); 
else if(C*hPrint)->prinfo.iDev == IDEV12) 
pushradiobuttonttp, CPI 12BUTTON, CPI 19BUTTON, CPI 15BUTTOND; 
else if(€C*hPrint)->prinfo.iDev == IDEV15) 
pushradiobutton( tp, CPI 15BUTTON, CPI 1@BUTTON, CPI 15BUTTOND; 
pushradiobut ton( tp, STRAIGHTUPITEM,STRAIGHTUP ITEM, SIDEWAYSI TEM); 
tp->»pFltrProc = (ProcPtrOMyFilter; 
tp pItemProc = (ProcPtr )HandleStylel tems; 
tp->hPrintUsr = hPrint; 


return( tp); 


/* 
* The job dialog initializer. 
x 


/ 
pascal ТРРгО10 MyPrJobInitChPrint) 
oe hPrint; 


TPPrD1g tp; 
int thenum; 
Handle theitem; 
Rect thebox; 
Str36 title; 


{р = TPPrD1gal locate); 

(GetNewDialogCJOBDIALOG, tp, - 122; 

pushradiobutton(Ctp, ALLBUTTON, ALLBUTTON, RANGEBUTTON); 

ifC C*hPrint)-»prStl.feed == feedCut) 
pushradiobutton( tp, SHEE TBUTTON, FANBUTTON, SHEETBUTTON); 

else 
pushradiobutton( tp, FANBUTTON, FANBUTTON, SHEETBUTTON); 

GetDI tem( tp, FROMNUM, &thenum, &thei tem, &thebox); 

thenum = C*hPrint)- prJob. iFstPage; 

NumToString(Clong)thenum, title); 

SetITextCtheitem, title); 


GetDI tem( tp, ТОМОМ, & thenum, & the i tem, & thebox); 
thenum = (*hPrint)->»pruob. iLstPage; 
NunToStringCClong2thenun, title); 
SetITextCtheitem, title); 


GetDI tem( tp, COPIES, &thenum, &the item, &thebox); 
thenum = (*hPrint)->»pruob. iCopies; 

NumToS tring(C long) thenum, title); 
SetITextCtheitem, title); 


tp-?»pFltrProc = СРгосРіг )MyFilter; 
tp->pItemProc = (ProcPtr )HandleJobI tems; 
tp~>hPrintUsr = hPrint; 

return(tp); 


) 

pascal Boolean MyPrD1lgMainChPrint,pDlgInit) 
/* Printing dialog supervisor function. */ 
/* Reference: Macintosh Technical Note */ 
/* 95. Good luck! */ 

THPrint hPrint; 

Мы pDigInit; 


ТРРг010 tp; 

WindowPtr tempport; 

int доле уре, itemhit; 

Handle doneiten; 

Rect — donebox; 

ProcPtr itemproc; 

asm ( 

subq.1*4,a7 5 
move. lhPrint, -(D;; 
nove. IpDiginit, ай; T 
jsr (að) 14 
move. 1 (a7)+, tp 23 


Room for function return. 

Pess handle to print record. 

Get addr. of dialog init routine. 
It’s a “Pascal” routine. 

Pop return value. 


itemproc = tp-»pItemProc; 
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tp->fDone = FALSE; 

tp->fDoIt = FALSE; 

GetPor tC&temppor t ); 

SetPort(tp); 

ShowW indow( tp); 

GetDI tem( tp, DONEI TEM, &done type , &done item, &donebox); 

PenSize(3,3); 

InsetRect(&donebox, -4, -42; 

FremeRoundRect (&donebox, 16, 16); 

whileC!(tp-> fDone)){ 

Mods IDialog( tp->pFltrProc, &itemhit); 

/* 

* Reverse parameters on the call to pItemProc. The applica- 
tion is allowed to trap our pItemProc and insert its own, so 
we must use the Pascal calling conventions here. Programming 
novices can use the LightspeedC™ Са11Раѕса1 library if they 
want. You will have to be careful if you do this to make sure 
the library is linked AFTER the module containing these 
functions, or you won’t get the PDEF resource header right. 

х/ 
asn( 
move.1tp,-Ca7) 
move .witemhit,-Ca7) 
move .]itemproc, ad 
jsr (ad) 


) 

SetPortCtempport); 

CloseDialog(tp); 

freeCtp); 

ifCtp->fDoIt) Cvoid)MyPrVal idateChPrint); 
return(tp-> Р0оІ+); 
/* 

* Validate/update a print record. Check 811 the fields for 
compatibility with our driver. This is a three stage process. 
First, we check 811 fields to see whether they ere within the 
bounds which our driver can handle. If they are, we return 
FALSE (по change). If not, we obtain а copy of the current 
default values from the printer resource file. Then we 
inspect these to see if they ere valid. If the default values 
in the printer resource file are valid, we use them, update 
the user's print record, and return TRUE (changed). Other- 
wise, we fall back on default values which we store in the 
code here. This three stage process provides some protection 
against the user who attempts to adjust the print record using 
а resource editor, and screws up. 

*/ 
pascal Boolean MyPrValidateChPrint) /* Validate/update а 
print record. */ 
pons hPrint; 


THPrint — thedefeult; 
ifCValidChPrint?)) return FALSE; 
else( 
thedefault = CTHPrint)(GetResource '"PREC^,022; 
LoadResource( thedefault); 


ifCthedefeult == nil || 1Val id( thedefeult)) 
mkDef aul tChPr int); 
else( 
**hPrint = **thedefault; 


return TRUE; 


) 
pascal void MyPrJobMergeChPr intSrc,hPrint0st) 
/* 


* Copy а job subrecord. Update the destination record’s 
printer information, band information, and paper rectengle, 
based on information in the job subrecord. 

%/ 

Тер hPr intSrc,hPrintDst; 


C*hPrintDst)-prinfo. iDev = (*hPrintSrc)-»pr Info. iDev; 
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C*hPrintDst)->»prJob = C*hPrintSrc)- prJob; 
C*hPrintDst)->»prxXInfo = C*hPrintSrc2- prXInfo; 
(*hPrintDst)->rPaper = C*hPrintSrc)- гРарег; 
C*hPrintDst)->prinfo = C*hPrintSrc)- prInfo; 
ChPrintDst)-»prInfoPT = C*hPrintSrc)->prinfoPT; 


) 

pascal Boolean MyFilterCthedialog, theEvent, itemhit) 
DialogPtr thedialog; 

EventRecord *theEvent; 

int *itemhit; 


ifCtheEvent-»what == keyDown && 
CtheEvent-?message & charCodeMask) == 13) ( 
*itemhit = 1; 
return TRUE; 


return FALSE; 


/* 

* The next routine handles the style dialog. Two possibili- 
ties exist. If the cancel button is hit, then we signal quit. 
The print record is not changed. If the done button is hit, we 
validate the user's print record. 

ж (MyPrD1gMainC) calls MyPrValidate() to do this.) 

* We use three redio buttons to determine the number of 
characters per inch (resolution), and two to determine paper 
orientation. 

xi 
pascal void HendleStyleItemsCtp, itemhit) 

TPPrDlg tp; 
int itemhit; 


int thenun; 
Handle theitem; 
Rect  thebox; 
ifCitemhit >= CPI10BUTTON && itemhit <= CPII5BUTTOND 
pushradiobutton( tp, i temhit,CPI10BUTTON, CPI 1SBUT TON); 
else ifCitemhit >= STRAIGHTUPITEM && itemhit <= SIDEWAY- 
SITEM) 


pushradiobutton( tp, i temhit, STRAIGHTUP ITEM, SIDEWAYSITEM); 


else ifCitemhit == DONEITEM)( 

TPrint Print; 
TPPrint pPrint; 
pPrint = &Print; 
nkDef eultC&pPr int); 
(*tp— hPrintUsr)-» iPrVersion = Print. iPrVersion; 
(*tp—hPrintUsr)-prInfo = Print.prInfo; 
(*tp-^hPrintUsr2)-?prXInfo = Print.prXInfo; 
C¥tp->hPrintUsr)->»rPaper = Print.rPeper; 
C¥tp->hPrintUsr )-»prStl = Print.prStl; 
C¥tp->hPrintUsr)-»prinfoPT = Print.prInfoPT; 
GetDI temCtp, CPI 19BUTTON, &thenum, &thei tem, &thebox); 
if GetCtlValueCtheitem) == 1){ 

(¥tp->hPrintUsr )->prinfo.iDev = IDEV10; 


GetDI temC tp, CPI I2BUTTON, & thenum, &thei tem, &thebox); 
if (GetCtlValueCtheitem) == 1) ( 
(*tp-»hPrintUsr2-?prInfo.iDev = IDEV12; 


) 
GetDItemCtp,CPI15BUTTON, &thenum, &thei tem, &thebox); 
if(GetCtlValueCtheitem) == 1) ( 

(ttp hPrintUsr)-?prInfo.iDev = IDEV15; 


GetDI tem( tp, SIDEWAYSITEM, &thenum, & the i tem, & thebox ); 
ifCGetCtlValueCtheitem) == 1) ( 
int temp; 
flipRectC&C*tp-—»hPrintUsr 2)-? prInfo.rPage); 
flipRectC&C*tp-»hPrintUsr2-»rPeper 2; 
fl ipRect(&C*tp->hPrintUsr )-) prInfoPT .rPage); 
temp = (*tp->»hPrintUsr )->prSt1. iPageV; 
(*tp->hPr intUsr )- prSt1. iPageV = 
(*tp hPr intUsr )->prSt1. iPageH; 
(¥tp->hPrintUsr )-? prSt1. iPageH = temp; 
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tp->fDone = TRUE; 
tp->fDoIt = TRUE; 


else if Citemhit == CANCELITEM){ 
tp->fDone = TRUE; 
tp-?fDoIt = FALSE; 


) 
pascal void HandleJobI tems( tp, itemhi t) 
TPPrDlg tp; 


int itemhit; 


int — thenum; 
long thelong; 
Handle numiten; 
Rect numbox ; 
Str36 title; 
if Citemhit == DONEITEMD( /* NO SWITCHES! */ 
tp-?fDone = TRUE; /* At least until I get a */ 
tp->fDoIt = TRUE; /* better compiler. */ 
GetDItemCtp, ALLBUTTON, &thenum, &nun item, &numbox?; 
if(GetCt]lValueCnumitem) == 1)( 
(*(tp-»hPrintUsr))-»prJob. iFstPage 


iPrPgFst; 
(*Ctp—hPrintUsr2)-?prJob. iLstPage 


= iPrPgMex; 

else( 
GetDItemCtp,FROMNUM, &thenum, &num i tem, &numbox ); 
GetITextCnumitem,&title[01); 
StringToNunC&title[9],&thelong); 
(*CtphPrintUsr2)-— prJob.iFstPage = thelong; 
GetDItemCtp, ТОМОМ, &thenum, &numitem, &numbox?; 
GetITextCnunitem,&title(01); 
Str ingToNunC&title[2],&thelong); 
(*(tp->hPrintUsr ))->prJdob. iLstPage = thelong; 


GetDItemCtp, COPIES, &thenum, &numi tem, &numbox?; 

GetI TextCnumitem,&title[91); 

Str ingToNum(&title(8],&thelong); 

(¥(tp->hPr intUsr ))-?prJob.iCopies = thelong; 
GetDI tem( tp, SHEETBUTTON, & thenum, &numi tem, &numbox ); 
if(GetCtlValueCnumitem) == 1){ 

(*Ctp— hPrintUsr2)-— prStl.feed = feedCut; 


) 
else (*Ctp->hPrintUsr ))->prStl.feed = feedFanfold; 


) 
else if Citemhit == CANCELITEM)( 
tp-»fDone = TRUE; 


else if Citemhit == SHEETBUTTOND( 
pushradiobut ton( tp, SHEETBUTTON, FANBUTTON, SHEE TBUTTON); 
€*Ctp->hPr intUsr ))->»prStl.feed = feedCut; 


) 

else if Citemhit == FANBUTTOND( 
pushradiobut ton( tp, FANBUTTON,FANBUTTON, SHEETBUTTON); 
(*(tp->hPrintUsr ))->»prStl.feed = feedFanfold; 


else if Citemhit == ALLBUTTOND( 
pushradiobut ton( tp, ALLBUTTON, ALLBUTTON, RANGEBUTTON); 


else if Citemhit == RANGEBUTTOND( 
pushrediobutton(Ctp, RANGEBUT TON, ALLBUT TON, RANGEBUTTON); 


) 
TPPrOlg TPPrD1gal locate() 


ТРРг019 thepointer; 
esn( 
move. 189 DLGSIZE, dO 
NewPtr 
move. 189, thepointer 


if(thepointer == nil){ — /* We're in deep six now! */ 


asm { 
move .w®25 , d 
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SysError ;; SysError 


return(thepointer); 


void pushradiobuttonCthedialog, itemhit, first, last) 

/* push a radio Button */ 
/* set itemhit, unset */ 
/* all others in range */ 


DialogPtr thedialog; 
ч itemhit, first, last; 


int itemtype, i; 

Handle itemhandle; 

Rect itemrect; 

ifCfirst ==8) return; 

forCisfirst-1;lest-i**;2( 
GetDItemCthedialog, i, &itemtype, &i temhandle, &itemrect); 
if(i == itemhit) SetCtlValueCitemhandle, 1); 
else SetCtlValueCitemhandle, 0); 


/* Does check boxes, too. */ 


) 
NumToString( thenum, thestring) 
long  thenum; 

cher  *thestring; 


asn ( 
поуе.1 thestr ing, a 
поме. 1 thenum, а0 
move .w®Q,-Ca7) 
Pack? 


) 

Str ingToNumCthestr ing, thenum) 
cher  *thestring; 

as *thenum; 


asn ( 
move. thestr ing, аб 
move .w®1 -Ca7) 
Pack7 
move . 1 thenum, ad 
move . 1 dð, (ай) 
) 
) 
/* 
* This function answers the question: Can we possibly use 
this print record? 
x 


Boolean — Valid(hPrint) 
THPrint hPrint; 


( 
if CCC*hPrint)-> iPrVersion != VERSION) 
|| €C*hPrint)->prinfo.iDev != IDEV12 && 
C*hPrint)-»prinfo.iDev != IDEV1O && 
(*hPrint)->prinfo.iDev != IDEV15) 
|| (C*hPrint)->prinfo.iVRes != VREZZ) 
|| (C*hPrint)->»prinfo.iHRes != HREZZ12) 
|| (C*hPrint)->»prinfo.rPage.top !=0 || 
C(*hPr int2-?prInfo.rPege.left !-0) 
|| CC#hPrint)->rPaper right - 
(*hPrint)->rPaper.left > 11 * HREZZ 12) 
|| (C*hPrint)->rPaper bottom - 
ChPrint)-»rPeper.top > 11 * VREZZ) 
|| CC#hPrint)-»prStl.feed != feedCut && 
(*hPrint)->prStl.feed != feedFanfold) 
|| (C*hPrint)->prJdob.bUDocLoop != bDraf tLoop)) 


return FALSE; 
else return TRUE; 


void free(ptr) 
on Xptr; 


esn( 
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move. ]ptr, ad 
DisposPtr 


) 
flipRect(rect) 
Rect  *rect; 


asm ( 
move. lrect,ad 
move. 1 (að), dð 
swap 40 3, swap top, left 
move. 100, (að )+ 
move. 1 Саб) ,а0 
swap d ;, swap bottom, right 
move. 140, (ад) 

) 

) 


*include “mkDefault.c” 


/* 
* PDEF5.c 
x 


* Although this printer driver does not do spool printing, I 
provide а duplicate PDEF to pretend to do so. That is just a 
copy of my PDEF 0, and it really does draft printing. This 
module is so the application can call PrPicFile() when it is 
done. Some applications just don’t get the hint, and attempt 
to spool print even when the print record says otherwise. 

x 


8include “prglobals.h” 
pascal void myPrPicFileC); 
nainC) 


esn( 
dc.w ILLEGAL 
jmp myPrPicFile 


pascal void = myPrPicFileChPrint, pPrPort, p10Buf , pDevBuf ,prStatus) 
THPr int hPr int; 


TPPrPor t pPrPor t; 
Ptr pIOBuf , pDevBuf ; 
Шан *orStatus; 
) 
/* 
* PACK.c 
x 


* Code for PACK ID -4896 to be used with the Chooser to set 
the printing port options. Set the Flags longword in the PACK 
resource to 0400Е000 after building the PACK resource to make 
Sure we get the right-hand button message. 

t, 


"include «WindowMgr.h? /* includes QuickDraw.h, MacTypes.h */ 
*include «DialogMgr.h? 

include *prglobals.h^ 

/* 


* Resources which are standard type and accessed by the PACK 
-4096 resource have ID * RES1ID. Resources which are non- 
standard type and/or belong without a doubt to our driver code 
ere accessed with RES2ID. These include the Stng resource and 
our PREC 8-8192. СІМ 4 says standard resource types to be 
used by this PACK resource should have IDs in the range -4080 
to -4065.) 

*[ 


/* Printer Setup Dbox item numbers.. */ 
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define SAVEITEM 1 
define MODEM 5 
Üdefine PRINTER 6 
"define BAUDBUTTON 8 
“define X EOLITEM 11 
“define ІМІТІТЕМ 12 
"define ТОРІТЕМ 13 
"define ЕОРІТЕМ 14 
define ЕОҒІТЕМ 15 
define — CTSITEM 19 
define — XONXOFFITEM 20 
"define — CANCELITEM 21 
define NUMSTRINGS 5 
"define RESPAD 24 


pascal OSErr main(message caller, ob jname, zonename, p 1, p2) 
int message,caller; 

StringPtr objname,zonename; 

(9 р1,р2; 


if (message == buttonMsg)( 
prsetup(); 


return СпоЕгг); 


pushradiobut ton( thedialog, itemhit, first, last) 
redio Button */ 
DielogPtr thedialog; 
Ж itemhit,first,last; 


/* set itemhit, unset */ 
/* all others in range */ 


int itemtype, i; 
Handle itemhandle; 
Rect itemrect; 
ifCfirst ==8) return; 
forCisfirst-1;lest-i**;2( 
GetDItenCthedialog, i, &itemtype, &itemhendle,&itemrect); 
ifCi == itemhit) SetCtlValueCitemhandle, 1); 
else SetCtlValueCitemhandle,9); 


/* Does check boxes, too. */ 
/* (when range is 1 in size.) */ 


) 
prsetup() 


DialogPtr printdialog; 
WindowPtr tempport; 
int itemhit, i, baudtype, edittupe, donetype; 
Handle baudi tem, doneitem,edititem; 
Rect baudbox, donebox, edi tbox; 
Str255 thestring; 
unsigned char*strptr; 
long  length,result; 
BAUDS **mybauds; 
Pfgsettings; 
StrList mystrings; 
mybauds = (BAUDS **)GetResource( ‘PREC’, RES21D); 
if(mybauds == nil) return; 
if CCsettings = (PfgoCGetResourceC ‘Stng’,RES2ID))) == nil 
|| Cmystrings = (StrList) (GetResource( ‘STR®’,RES1ID))) == 
nil) 


return; 
if (pbaud<@ || pbaud»9) pbaud = Ø; 
ifCCprintdialog = GetNewDialogCRES1ID, OL, CWindowPtr) -1)) 
== nil) 
return; 
GetDI tem(pr intdialog, BAUDBUTTON, &baudtype , &baudi tem, &baudbox ); 
GetDI temCprintdialog, SAVEITEM, &done type , &done i tem, &donebox) ; 
SetCTitleCbaudi tem, (C*mybauds )*pbeud)-? label ); 
/* This gets the printer control strings from a string list, 
then sets the editText items in the dialog box to contain the 
strings. 
x 


strptr = &CC*nystrings2-? thestr ings(2 1); 

for(i = EOLITEM-1;EOFITEM - it+;){ 
GetDI temCpr intdialog, i, &edittype, kediti tem, &edi tbox); 
SetITextCedititem,strptr); 
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/* push а 


strptr += (%strptr) + 1; 


Ge tPor t(& tempport); 
SetPor tCprintdialog); 
ShowW indow(pr intdialog); 
PenSize(4,4); /* Time to frame some buttons. */ 
InsetRect C&donebox, -5, -52; 
FrameRoundRect (&donebox, 16, 16); 
PenSize(2,2); 
InsetRect (&baudbox ,-3,-3); 
FremeRoundRect (&baudbox, 12, 12); 
pushradiobutton(printdialog, pport + MODEM,MODEM, PRINTER); 
pushradiobutton(printdialog,CTSITEM + XonXoff,CTSITEM, 
XONXOFF ITEM); 
itemhit = 0; 
whileCitemhit !=1)( 
ModalDialogCOL, &itemhit); 
switch itemhit){ 
/* Port change. It might be nice to check and see whether 
AppleTalk is active if the user selects the Printer Port.. */ 
case MODEM: 
case PRINTER: 
pport = itemhit - MODEM; 
pushradiobutton(pr intdialog, itemhit, 
MODEM, PRINTER); 
break; 
case BAUDBUTTON: /* next baud rate change */ 
/* Ten radio buttons would be just too much. */ 
if €++pbaud == 10) pbaud = 0; 
SetCTitleCbaudi tem, (C*mybauds)+pbaud)-> label); 
break; 
case CTSITEM: 
case XONXOFFITEM: 
XonXoff = itemhit – CTSITEM; 
pushradiobut ton(pr intdialog, 
itemhit, CTSITEM, XONXOFF ITEM); 
break; 
case CANCELITEM: 
DisposDialog(printdialog); 
SetPortCtempport); 
return; 
break; 


/* The user has set the beud rete end the port, and also 
possibly edited the printer control strings. Since we used 
ModalDialog() with no filterproc we don’t know whether any of 
the strings heve been chenged. Therefore we just rebuild the 
whole string list. First, determine the length. */ 


length = (long? (sizeof Cint)*RESPAD2; 

for(i = EOLITEM-1;EOFITEM - i**;2( 
GetDItemCprintdialog,i,&edittype,&edititem, &editbox2; 
GetITextCedititem, thestr ing); 
length += (long) thestring(2]; 


) 
/* Size might have changed, so we unlock the handle апа 
ettempt to resize it. */ 
asm ( 
move.lmystrings,e0;; save loading MacTreps 
-HUn lock 
move. 1 mystrings, ad 
move. 1 length, dO 
-SetHendleSize 
move. 1nystrings, аб 
_GetHandleSize 
move. 140, result 


if С result != length )( /* Abort on error. */ 
DisposDialog(printdialog); 
SetPortCtempport); 
returnCFALSE); 


esn( 
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nove.1mystrings, 80 
-HNoPurge 

move. ]1mystrings, 80 
-HLock 


) 

/* Rebuild the STR® from the item list. */ 

strptr = &CC*nystrings2-? thestr ings[2 1); 

for(i = EOLITEM-1;EOFITEM - i**;2( 
GetDItenCprintdialog, i, &edittype, &edititem, &edi tbox); 
GetITextCedititem,strptr); 
strptr += (*strptr) + 1; 


DisposDialog(pr intdialog); 
SetPor tC temppor t); 
ChangedResource(settings); 
ChangedResource(mystr ings); 
Wri teResource(settings); 
Wri teResource(mystr ings); 
return; 


/* 
* mkDefault.c 
x 


* This function fills a print record with defaults, using 
coded values. It is used only when the default print record 
stored in the printer resource file is found to be invalid. 
It’s also for the code to make the first copy. According to a 
compile-time switch, margins are either zero or one inch all 
around, zero on the right. To support paper which has more 
than 66 lines per page or 164 columns, you have to make 
changes here and in PDEF@.c. 

*/ 

"def ine ONE_INCH_MARGIN 1 
void mkDefault(hPrint) 
ere hPr int; 


C*hPrint)-> iPrVersion = VERSION; 
C*hPrint)->prinfo.iDev = IDEV12; 
C*hPrint)->prinfo. iVRes = VREZZ; 
(*hPrint)->prinfo. iHRes = HREZZ 12; 
C*hPrint)->prinfo.rPage.top = 0; 
C*hPrint)->prinfo.rPage. left = 0; 


#if ONE_INCH_MARGIN 
C*hPrint)->prinfo.rPage.right = HREZZ12 * 7; 
C*hPrint)->prinfo.rPage.bottom = VREZZ х 9; 
(*hPrint)-»rPaper.top = -VREZZ; 
C*hPrint)->»rPaper. left = -HREZZ 12; 
(*hPrint)-»rPaper .bottom = VREZZ * 10, 
C*hPrint)->rPaper right = HREZZ12 * 7 + HREZZ12/2; 
else 
ChhPrint)- prInfo.rPage.right = HREZZ12 * 8 + HREZZ12/2; 
C*hPrint)->prinfo.rPage.bottom = VREZZ * 11; 
C*hPrint)-»rPaper = C*hPrint2-»prInfo.rPage; 
"endif 


ChPrint)-)prStl.wDev = iDevDaisy; 
ChPrint)- prStl.iPageV = 11 * iPrPgFract; 
ChPrint)- prStl.iPageH = Cintd(Cfloat)iPrPgFract * 8.5); 
ChhPrint)- prStl.bPort = Ø; 
C*hPrint)->prSt1.feed = feedFanfold; 
C*hPrint)-»priInfoPT = (*hPrint)->prinfo; 
C*hPrint)->prXInfo. iRowBytes = 0; 
C*hPrint)->prXInfo. iBandV = 8; 
C*hPrint)->prXInfo. iBandH = 0; 
(*hPrint)->prXxInfo. iDevBytes = 0; 
C*hPrint)->prxInfo. iBands = 0; 
(*hPrint)->prXInfo.bPatScale = 9; 
C*hPrint)->»prXInfo.bULThick = 0; 
ChPrint)-»prXInfo.bULOffset = 0; 
ChhPrint)-?prXInfo.bULShadow = 0; 
ChhPrint)- prXInfo.scan = scenLR; 
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(*hPr int2-»prXInfo.bXInfoX = 0; 
(*hPrint)-»prdob. iFstPage = 1; 
(*hPrint)-»prdob. iLstPage = iPrPgMax; 
(*hPrint)->prdob. iCopies = 1; 
(*hPrint)-»prdob.bUDocLoop = bDraf оор; 
(*hPrint)-»prdob.fFromUsr = TRUE; 
(*hPrint)->prdob.pIdleProc = nil; 

(*hPr int )-»prJob.pFileName = nil; 
(*hPrint)->prdob. iFileVol = 8; 
(*hPrint)->prdob.bFileVers = 8; 

(*hPr int2-?prJob.bJobX = 0; 

(thPrint)-— printX(201 = 
CthPrint2- printXE1] 
C*hPr int )-? printX[2) 
CthPr int )-> printX[3) 
(*hPr int )-> printXx[4] 
(*hPr int )-> printX[5) 
C*hPr int)? printx [6] 
C*hPr int )-> printX(7) 
C*hPr int )-> printx(8] 
C*hPr int )->printx(9] 
C*hPr int) printXC 10] 
CthPr int) printXE 11] 
C*hPr int) printXC 12] 
C*hPr int) printXE13] 
C*hPr int )-? printX[ 14] 
C*hPr int )-? printX[ 15] 
C*hPr int )->printX[ 16) 
C*hPr int )—>printXx[17) 
C*hPr int) pr intX( 181 


) 

/* 
* Utils.c 
x 


* Utility program to format the code resources used with the 


Daisy printing manager. If you run it twice, it does no 
the second time. 
*/ 


8Sinclude “prglobals.h” 
#def ine PAD24L 
typedef struct ( 
unsigned int flags; 
unsigned int delay; 
unsigned int emask; 
unsigned int menu; 
)driver , *Pdriver , **Hdr iver; 
void rkDef aut: 
nain(C) 


setpackf lags(); 
setdriverflags(); 
createPDEF(*\psrc:Pr inter :DaisyPDEFO”, 0); 
createPDEF(”\psrc:Pr inter :DaisyPDEF 4”, 4); 
createPDEF(”\psrc:Pr inter : DaisyPDEF5”,5); 
) createPREC( 5; 
/* 

* This is e utility function to strip off the header by 
LightSpeedC puts on Code Resources it creates. I put an 
illegal instruction right before the code I want. 

x 


createPDEF (filename, idno) 
char *filename; 
int idno; 


long thesize; 
unsigned int **thehandle, **newhandle; 
unsigned int *theword, *newone; 
int thef ile; 
int result; 
thefile = OpenResF ile(f ilename); 


thing 


tes 


thehandle = (unsigned int **) GetResource( ‘pdef’, idno); 


if Cthehandle == ØL) return; 
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else( 
эы ы = SizeResourceCthehandle) + PAD; 
850 
move . 1thehandle, að 
-HLock 


theword = *thehandle; 
while(*theword++ != ILLEGAL) ( 
thesize -=2; 


esn( 
nove. 1thesize,d0 
-NewHandle 
move . 180 ,newhandle 


if (newhendle == OL) return; 
else ( 
asm ( 
move. Inewhandle, að 
-HLock 
nove. 1(a0),newone 
move . 1theword, e 
nove. Inewone, a1 
move. ]thesize, 40 
-BlockMove 
move .wd9,result 


if Cresul toreturn; 
AddResource(newhandle, ^PDEF ^, idno, “\pStripped РОЕҒ”); 

WriteResourceCnewhandle?); 

RmveResource( thehandle); 

UpdateResF i leCthef ile); 

CloseResF ileCthef ile); 


) 
) 
setdriverflagsC) 


Hdriver — Xprint; 
OpenResF i leC^Apsrc:Pr inter :DeisyDRVR^); 
Xprint = СНагіуег )(GetResource( ‘DRVR’ ,2)); 
(*Xprint)->flags = dCtlEnable | dStatEnable; 
(*Xprint)- delay = 0х0000; 
(*Xprint)-?emesk = 0х0000; 
C*Xprint)->menu = 0х0000; 
ChangedResource(Xpr int); 
WriteResource(Xpr int); 


/* This function sets the version number and flags for the 
PACK resource used to interface with the Chooser. */ 
setpackf lags() 


long  **pack; 
OpenResF ileC^Mpsrc:Pr inter :DaisyPACK” ); 
pack = (long **)(GetResource( ‘PACK’, -4996)); 
if (pack != ØL)( 
*((*Xpack)*2) = OxF 0000001; 
*(C*pack)*3) = 0x0400E000; 
ChengedResource(Cpack 2; 
Wr iteResource(pack); 


/* Create a default printer settings resource based on the 
same code used in our printer resource file. */ 
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createPRECC) 


THPrint — thehandle; 
CreateResF i leC”\psrc:Pr inter :DeisyPRECO^); 
OpenResF i leC"Mpsrc:Pr inter :DeisyPRECO ^); 
SetResLoadC TRUE); 
tone а ай ыы 
esn 
nove. 1? CClong?sizeof CTPr int 22, 40 
NewHandle 
move. 188, thehandle 


mkDefaultCthehandle); 
AddResource( thehandle, "PREC^,8, "\рРгіпі defaults”); 
Wr i teResource( thehandle); 


#include “mkDefault.c” 
* Daisy.r file puts it all together 
x 


bin: sys: Daisy 

PRERDasY 

*Include dialogs 

INCLUDE src:Printer :dialogs.rsrc 

Type PDEF = GNRL 

Draft Printing Соде,0 (48) ;; locked, Purgeable 
R 


src:Printer :DaisyPDEF® PDEF 0 

*Tupe PDEF = GNRL 

*5роо1 Printing Code,1 (48) ;; locked, Purgeable 
zR 


*src:Printer:DaisyPDEF 1 PDEF 1 
x 


Type PDEF = GNRL 
Dialog Code,4 (48) ;; locked, Purgeable 
R 


src:Printer :DaisyPDEF4 PDEF 4 
Туре PDEF = GNRL 

PrPicFile stub,5 

R 


erc:Printer:DaisyPDEF5 PDEF 5 

Type DRVR = GNRL 

.XPrint,-8192 (32) ;; attributes -> Purgeable 
R 


src:Printer :DaisyDRVR DRVR 2 

Type PACK = GNRL 

Daisy Config,-4096 (32) ;; attributes -> Purgeable 
R 


src:Printer :DaisyPACK PACK -4096 
Туре PREC = GNRL 


д 


R 

src:Printer :DaisyPREC® PREC 0 
Type PREC = GNRL 

‚1 

R 


src:Printer :DaisyPRECB PREC 0 
Type PREC = GNRL 

,-8192 

R 


src:Printer:DaisyDRVR DATA - 16328 

Type STR 

278191 

Print File А. 
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Pascal 
Procedures 


Intermediate Mac 'ing 


The Generic Multi-Window Text Editor 


Nostalgia 

This is a column in nostalgia. A throwback to the good old 
days of 1986 when Mac programs were done by hand with event 
loops, menu bars and custom designed scroll routines. Back 
when men were men and programmers who knew how to write 
a multi-window text editor were looked up to as heros of the Mac 
programming cult. Yes, back in the dark ages before MacApp 
made all of what you are about to read obsolete. So take a ride 
with us into the stone age of Mac programming and see how it 
used to be when programmers struggled to code up a multi- 
window application from scratch. 

Programming Puberty 

Before MacApp, it was taken for granted that to reach 
programming puberty, you had to write a multi-window editor. 
The reason for this is such a program involves nearly all of the 
Mac user interface. Multiple windows, update events, scroll bars, 
text edit, cut and paste, and so on. A number of these generic 
editor shells have been published in both shareware, books and 
magazine articles. Bob Denny wrote one of the first such articles 
for MacTutor in May 1985 with a discussion of text edit and 
scrolling windows that remains a classic on the subject. Several 
previous articles in that series delt with editing using the C 
language. All of those articles are available in the Best of 
MacTutor, Volume 1 book. 

The Chernicoff book, Macintosh Revealed, Volume 2, pro- 
vided an entire book on the subject of the multi-window text 
editor in Pascal. This is a very complete description of such a 
program and covers most of the material in Inside Macintosh, vol. 
1-3. Another book is the very good series by Dan Weston, The 
Complete Book of Macintosh Assembly Language Program- 
ming, Volumes I and 2. The first volume covers the generic text 
editor in assembly, and volume 2, just released, goes farther in 
explaining new programming details of using the switcher, HFS, 
clipboard and other topics generally discussed in Inside Macin- 
tosh Volume 4. Most of the material in volume 2 of Dan Weston's 
book has never been published and represents a very important 
book regardless of what language you program in. Be sure to buy 
this book without delay. Scott, Foreman and Company are the 
publishers. 

Finally, one of the most complete multi-window text editors 
is the source listing supplied with LightSpeed Pascal from Think 
Technologies. This programming example is very complete and 
will provide an excellent Pascal reference. It is generally based 
on the Chernicoff example but expands on it in many areas. 

Which brings us to this rendition of the generic multi- 
window text edit example. Not wanting to miss out on my own 
Opportunity at programming manhood, I decided to write my 
own text editor using all the references cited above as guides. The 
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Fig. 1 Our Multi-Window Editor 


result is the subject of this month's column. Although it took three 
months, and I think is a very good start, I was a bit taken back 
when Harvey Alcabes of Apple Computer showed off MacApp 
and demonstrated the simplest "do nothing" MacApp applica- 
tion. It was an advanced version of my program! Since this may 
become a lost art, I present my version of the generic text editor 
for those who wish to bash heads with the toolbox before moving 
on to MacApp. 
What Our Example Does 

As an application, our program is very complete. It opens 
four windows for text editing. Scrolling is supported vertically. 
All the window operations are supported including grow win- 
dow, close box, and zoom box. When either the grow box or 
zoom box is selected, the text is wrapped to the new window size 
So there is noneed for horizontal scrolling. A neat addition would 
be to include an option in the format menu where the user could 
select between the two modes of having the text wrap when the 
window changed size, or having the window scroll to view the 
text. The first mode is ideal for paragraph writing, like the text 
you are reading now. The second mode is better suited for 
program text or tables where placement of the text remains fixed 
at tab stops. Of course, Text Edit doesn't support tabs so this mode 
would require more work. The November 1986 issue of MacTu- 
tor presented a possible solution for extending Text Edit to 
handle tabs. 

Text presented in any of the four windows may be selected 
and changed to all the quickdraw / text edit possibilities. A font 
menu gives access to all the fonts in your system file. A size menu 
allows size changes from 6 point to 72 point with a dialog box for 
custom font sizes up to the quickdraw limit of 127. A style menu 
gives all the quickdraw styles available to text without any 
custom programming including condensed and extended text. 
Finally, the mode menu allows the three quickdraw recom- 
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mended modes for drawing text. After trying the different modes, 

I concluded that this is probably useless. But at least all the 

quickdraw text capability is supported in this text edit example. 
Text Edit Limitations 

As you know, text edit is a set of ROM routines which 
implement a simple text edit capability based on the ability of 
quickdraw. Only one font, style, size and mode is allowed for all 
the text in a given text edit record. Text Edit is also limited to 32K 
bytes of text and in fact the limit is even less depending on the font 
and size chosen. A more limiting factor is the destination rec- 
tangle that encloses the text. The coordinates of the rectangle are 
limited to integer values, but thesecan be quickly exceeded when 
a large font size, a small window, and many lines of text are 
combined at one time. This may explain why few programs allow 
complete freedom in text size selection. After playing with the 
size menu, I discovered that when my window was made narrow, 
and the size increased, the destination rectange limits were being 
exceeded in my routine to re-wrap the text to the new window. 
The product of the number of text lines calculated by Text Edit 
and the number of pixels per line, a function of the font size, 
quickly becomes greater than an integer value, making proper 
scrolling impossible. TEScroll generates an error since it is 
limited to an integer offset for the scrolling distance. In our 
program, when this happens, it beeps and the displayed text is 
scrolled to 32K, the max, which may not result in a correct 
window display. Reducing the font size or enlarging the window 
will correct the display. 

In figure 1, we see a screen shot of our program showing 
four windows open, each with a different font, size, and style. The 
edit menu supports cut, copy and paste to the Text Edit scrap. 
Since this scrap is a private scrap known only to text edit, I copy 
the TEScrap to the deskscrap whenever a copy or cut operation 
is performed. Likewise, when a paste is done, it is taken from the 
deskscrap. Thus the deskscrap is used at all times so that the 
private text edit scrap and the clipboard scrap are always the 
same. This allows an easy way to cut and paste between our 
windows and desk accessories or other applications without the 
problem of trying to figure out when to convert the clipboard. 

Figure 2 shows how our custom font size dialog works. The 
current size is displayed from a parameter variable in low 
memory and an edit item is provided so that a new value may be 
inserted. 

Our edit menu includes two useful functions shown in 
figure 3. These are a show clipboard, and a select all function. 
The select all highlights all the text in the text edit record and 
copies it into the deskscrap so that a subsequent paste operation 
will paste the selected text. This seemed the most natural to me 


Select Font Size: 24 


Figure 2: The custom size dialog box 
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and eliminates the extra step of choosing copy from the edit 
menu. For simplicity, the clipboard does not show the text in the 
selected font, nor does it scroll. You may wish to turn the 
clipboard window into another text type window so that it shows 
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Fig. 3 Clipboard and Select All 


the font and style of the selected text. 

The search and format menus do nothing. We have already 
made a suggestion for the format menu, to select between word 
wrapping or horizontal scrolling. The search menu can be imple- 
mented by using the munger trap call to search for arbitrary 
strings in the text editrecord. The font, style, and mode menus are 
fully implemented to the limit of quickdraw's built-in text com- 
mands. The transfer menu is not implemented but is ready to set 
up a standard file dialog box for launching another application. 
How this is done was covered in an earlier issue of MacTutor by 
Chris Yerga, available in the Best of book. The edit menu is fully 
operational except for UNDO. A future article on how to imple- 
ment undo is waiting publication in MacTutor. The apple menu 
shows a simple about box dialog with an icon and the desk 
accessories are available. The file menu has a new and close 
command, which open and close up to four new windows. A 
single global variable, MaxWindows, determines the number 
available. This method was chosen so that all the window data 
Structures could be set up low in the heap, since the window 
record is not re-locatable. The normal file and printing operations 
for opening and saving the file, and printing the file are not 
implemented. There is only so much one can do in a single article 
ona topic which others have written entire books about. Both of 
these subjects are well treated in Dan Weston's new volume 2 on 
assembly programming, previously mentioned. 

LightSpeed Pascal 

Figure 4 shows the files created by the LightSpeed Pascal 
system. The four text files shown can be read directly by Edit if 
you are using another Pascal system. As explained in last month's 
article by Tom Scheiderich, there is very little difference in 
running this program in TML or LS Pascal. Only the segmenta- 
tion is different. The program code is contained in a short 
"MyWrite Main" file. This includes the init code, the event loop 
and the first level of event subroutines. Two other files complete 
the program. These are the "myWriteStuff" unit and the "scroll- 
stuff" unit. Finally, the file "Editor Globals" contain the global 
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Figure 4: Edit Program Files 


constant and variable declarations. David Wilson, the Apple 
Programming guru, recommends that the init code be placed in 
the first segment so that it is always locked in memory. Appar- 
ently trying to place the init code in another segment that may be 
unlocked or purged can cause problems with the quickdraw 
global assignments. That is why I included the init stuff in my 
main program rather than in another unit as some people do. 
Resources are handled in the normal way. An edit file called 
"MyWrite.R" contains the RMaker formatresources. These must 
be assembled into a resource file named "MyWrite.RSRC". The 
actual program is contained as a project in "MyWrite Project", 
shown hi-lited in figure 4, and in a stand alone file created with 
the "build" command. The switcher test case file was used to test 
the switcher event to see that the clipboard worked properly from 
switcher. The ease with which you can get into and out of a 
development task by just clicking on the project file really makes 
working with LS Pascal a snap. And the observe window, which 
allows examining local variables makes debugging fast and easy. 
I love it! 
Segments 

Figure 5 shows the implied link order for our program. The 
globals and main files are linked together in segment 1 along with 
all the various Pascal system files. ROMSS is the library of new 
128K ROM calls, included just so I wouldn't have to think about 
it. I really don't know if I used any new calls or not. Most of the 
code is contained in "my Write Stuff", the main chunk of segment 
2. At the end of the event loop, an "unloadSeg" trap call is made 
to unload these two units, making them re-locatable. This type of 
segmentation by unit boundaries is unique to LS Pascal and you 
may wish to modify this if you are using another linker. 

MyWrite Program Code 

We begin our discussion of this program with the main 
segment, shown in figures 6, 7 and 8. The main program calls 
three routines to init everything, set up the menu bar, and perform 
the event loop, as illustrated in figure 6. The events our program 
responds to are shown in figure 7. These are a mouse down event, 
a keypress, and the update and activate events for windows. This 
represents the minimum response for a typical Mac application. 
We have included a fifth event, the switcher event, number 15, to 
detect when the switcher suspends and activates us. This was 
taken from Dan Weston's volume 2 book, which explains in great 
detail how the switcher works. Since we use the system scrap at 
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all times, we really don't need this event since no clipboard 
conversion is required. 

All the action takes place in the mouse down event, where 
we perform the menu bar functions. Figure 8 shows the various 


File (by seqment) 
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СІР 
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places the mouse can be and the implied action we must take. 
When aclick happens in the content region of a window, we have 
to find out if that is a scroll event, since the scroll bars are part of 
the content region of a window. So scrolling is done as part of a 
content region mouse down event. Grow and Zoom events are 
also handled. These events change the window size, and in our 
application, cause all the text to be re-formatted to wrap to the 
new view rectangle. This proved to be the hardest part of the 
program, getting grow window to work right. The little grow icon 
is apparently a lost child and it took quite a while to figure out how 
the window is grown and updated properly under all conditions. 
Data Structures 

Most of the published text edit examples use a custom data 
type called a window control block or some such thing to manage 
all the data structures associated with the window. Since I didn't 
want to confuse the toolbox data structures, which I was trying to 
learn, with the custom ones, I did not use this approach. Instead, 
I set up five arrays shown below: 

myWindows: array[1..MaxWindows] of Windowptr; 

GoodbyList: array[1..MaxWindows] of Integer; 

myVControls: array[1..MaxWindows] of ControlHandle; 

myHControls: array[1..MaxWindows] of ControlHandle; 
myText: array[1..MaxWindows] of TEHandle; 

The window array holds the window pointers to the window 
records. The text array holds the handles to the text edit records. 
The vertical and horizontal control arrays hold the handles to the 
scrollercontrols. Finally, the GoodbyList holds the status of each 
window, whether it is available or being used. The proper 
association of each control or text edit record to the proper 
window is done by the array index. The currently active index is 
contained in the global variable "currentWindow". MaxWin- 
dows is set at 4 but this can be changed in the global variables. 
From my background, this approach was the most logical to me 
and eliminated the need to create a custom variable type. How- 
ever, now that I've written the program and understand how the 
Mac works, I can see that it would be cleaner to combine all these 
arrays into a new data structure that would tie the various 
components toa "window object". This approach would also lead 
into a MacApp conversion more easily. The trick is you can't 
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appreciate this until after you've written such a program and 
understand more clearly how all the pieces fit together. 
Main Program Notes 

The first thing we do in our main program is init everything. 
Notice that we set up a bomb routine with our InitDialogs trap so 
that if a system error is generated, we get a resume box that will 
return us to our program where we can exit to the finder. Our 
bomb routine is called crash, and simply calls the toolbox routine 
ExitToShell. Scott Knaster, in his book How to Write Macintosh 
Software, goes into great length on how to write these saver 
routines. However there is some controversy on just how much 
such a crash routine should do. Trying to write to the disk to save 
a file after a crash could be bad news if the system is so fouled up 
that a hard disk is destroyed in the process. So I think it is better 
to assume the worse and just exit rather than try and be nice to the 
user only to find out you bombed his hard disk! Incidently, this 
is a very good book, which is not described by its title. It really 
is a book on how to debug Mac programs and is a must for 
everyone. The book is being distributed free if you join APDA, 
the official Apple developer's Association. 

Rectangles are very important. Our program uses several 
global rectanges for the window stuff. These are: 


screen screen display rectangle 
DragArea window drag rectangle 
GrowArea window grow rectangle 
DefaultWindow new window size default 
ZoomRect zoom area rectangle 


Main 
Program 


Figure 6: The Main Program 
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Figure 7: The Event Loop 
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Figure 8: The Mouse Down Event 


ClipBdRect clipboard window rectangle 
ViewRect vew rectangle for text edit 
DestRect destination rectangle for text edit 
VCRect vertical scroller area 

HCRect horizontal scroller area 
GrowRect grow box region 


All of these are set up in our init routine and are calculated 
from the system global ScreenBits.Bounds, so that they all 
change appropriately if a large screen is used. I tested the program 
оп alarge screen Mac and it worked perfectly. The Zoom window 
zoomed to the size of the large screen because of how these 
rectangles are defined relative to ScreenBits.Bounds. 

Another important point is the order in which things are 
done during init. The window must be defined first, followed by 
the controls and then text edit. Text Edit requires the current port 
be set properly to the window whoose text edit record is being 
defined. That is how the assocation is made between the text edit 
record and the window record. So you must define the window 
first, and then do a SetPort to that window before calling TENew 
to create the text edit record. 

The problem of getting the menus to show the right font and 
sizes is handled by calling UpdateMenus as shown in the SetUp- 
Menus routine. This in turn calls a routine for each menu which 
examines the current port settings and changes the menu appear- 
ance appropriately. Thus whenever a new window is activated, a 
call to UpdateMenus then changes the font and size menus to 
reflect the current font, size, style and mode for that window. You 
could also try to dim or hi-lite menu items as appropriate, but I 
have not done that here. If a menu item is selected when not 
appropriate, it beeps and nothing happens. This was done to help 
figure out potential bug bombs. Having done that, you can go 
back and select or unselect menu items as necessary. 

The doMouse routine calls each mouse event routine for 
grow, content and so forth. I attempted to make the grow routine 
universal so I could call it with ZoomWindow as well. When the 
window changes size, the text is re-calculated to fit the new port 
rectangle. In this respect, Zoom Window is really a grow window 
function. So the Zoom event does the standard ZoomWindow 
and then calls the doGrow event routine to update the window. 

The doKeyDowns routine checks for command keys and 
passes them back to the doMenuBar routine so that command 
keys are handled properly. Also the length of text in the text edit 
record for that window is checked so we don't type beyond 32K 
of text. This check is also made in the paste routine as well. 

Update Events 
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The final routines in our main program are the update and 
activate events. Trying to figure out how this is done properly for 
scrolling windows was a real challenge. I think I have the best 
sequence in my Update and Activate event routines, but if 
someone has a better approach, I'd like to hear about it. When the 
BeginUpdate trap is called, the port rectangle is changed to the 
update region. An EraseRect on the PortRect for that window will 
then clear out the update region. I then draw my controls and call 
TEUpdate for the visible region of the window. The current port 
is not changed. This seems to be the best approach for the update 
event. The activate and de-activate events do a show control and 
a hide control in addition to doing а DrawGrowlIcon. This seemed 
to be the best way to get the windows re-drawn properly under all 
conditions. If the clipboard window is being activated, we set our 
currentWindow global to 0 to indicate the active window is not 
one of our four text edit windows. The desk scrap is read into the 
text edit private scrap and the text edit record for the clipboard is 
updated. The clipboard text points to the text edit scrap so that 
whateveris in the textedit scrap will be displayed in the clipboard 
window. 

MyWrite Stuff Unit 

The heart of our program is contained іп the MyWrite Stuff 
unit. This includes all the second level subroutines for the menu 
bar functions, updating each of the menus, the about box, new 
window, close window, drag, grow and content routines. The 
only routines remaining are the scrolling routines, which are 
handled in a seperate Scroll Stuff unit. 

The fonts, size, style and mode menus are all somewhat 
similar. When the user selects a new font, the grafport's font is 
changed, the font menu is updated to show the selected font 
(UpdateFonts), and the textis bashed to re-wrap it to be displayed 
inthe text edit window. The Size menu works the same way. The 
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grafport's font size is changed, the size menu updated (Update- 
Size) and the text bashed to wrap the new text display in the 
window. The size menu includes a custom size that displays a 
dialog box from our resource file. The current font size is read 
from the grafport (thePort^.txSize) and placed in one of four low 
memory variables with the trap call ParamText. Then when the 
dialog box is displayed, the ParamText item is displayed in the 
dialog at the location specified in the resource file. In this way 
programs can pass information to a dialog box display. I was only 
able to get this to work for a static text item, and not for the edit 
text item. Anybody know why? The style menu also includes 
formatting of the display left, center and right. If the user selects 
anew format, the text edit record is updated and the text bashed 
after updating the menu (UpdateJust and UpdateStyle). Dealing 
with style items is really tricky and seems to take up a lot more 
programming space than if Apple had just assigned integer 
values to the various style selections. I found it particularly 
confusing trying to figure out how to tell if a given style was 
included in the currently selected text face. The doStyle routine 
shows how it works. 

The important routine of course, is BashText. This routine 
reads all the text information from the grafport (font, face, mode 
and size), gets the font ascent and height from the FontInfo 
record, and resets the text edit record to match the newly set 
values of the current grafport, which were set by each of the "do" 
menu routines for size, font, style and so on. Once the text edit 
record is up to date, then the text line starts are re-calculated 
(TECalText), the view rectange is marked as invalid, and the 
scrollers updated. Then when the update event is executed, the 
new text edit parameters will be reflected in the window display 
and the scrollers will be adjusted so that the selection point is still 
visible. 

Content and Grow Events 

The hardest part of the program was dealing with a content 
event or a grow window event. For a content event, we must find 
out which window the event occours in and then find out if the 
click is in the "real" content area or in the scrollers, which are 
treated by the window manager as part of the content region. If 
the scroller area was clicked, we call doScrollers. Otherwise, if 
the click is іп the view rectangle, we call TEClick, which handles 
ashiftkey down selection and hi-lites the selected text for us. The 
grow window routine must check for a zoom event from which 
to get the new window size or take the new size from the 
GrowWindow trap call. Once the new window size is deter- 
mined, we reset all our rectangles (VCRect, HCRect, GrowRect) 
and call SizeWindow to change the PortRect to the new size. 
Setting the rectangles before the SizeWindow gives the pre-size 
dimensions so we can Invalidate the grow icon region and erase 
it. Getting the grow icon area to update properly was the hardest 
part of this routine. The order in which the SizeWindow and 
updating of the grow icon region are done affects the appearance 
on the screen. I found the order shown in this routine seems to 
paint the screen in the fastest manner. 

After calling SizeWindow, the PortRect is changed. So we 
reset our rectangles, hide and move the controls to the new 
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positions, re-size the controls to the new dimension, and then 
show the controls. Then the control rectangles are marked as 
valid so they won't be re-drawn during the next update event, 
since we have already manually updated them. This order seems 
to produce the most pleasing display. Finally, we reset the 
ViewRect and DestRect and bash the text to re-wrap it to the new 
screen size. 
Scroll Stuff Unit 

The last unit is the scrolling routines. This stuff is magic. It 
is a combination of Bob Denny's early C routines, Chernicoff's 
Macintosh Revealed approach, and LS Pascal's text editor ex- 
ample. The heart of this unit is the MoveText routine. This 
routine simply scrolls the text to match the currently set control 
value. All the other scroll routines concentrate on setting the 
control values to their new values, then they call this routine to 
actually move the text by scrolling. The problem is that TEScroll 
only allows an integer offset to scroll up or down. That offset is 
given in pixels, so we multiply the number of lines (the scroller 
control value) by the line height and substract the result of any 
previous scroll to get the offset needed to scroll to the current 
control value. If the number of lines is large and the line height 
is large (large size), this value exceeds 32K even though the text 
buffer may be much less than 32K. As a result, TEScroll doesn't 
work and I don't know how else to move the text without it. 

Other bugs in Text Edit are also tested for in this routine. 
When calling TEScroll, you must make sure the scrolling offset 
is not zero. Also, the number of lines in the text buffer is not 
correct if a carriage return is the last character. So a special 
function called LinesInText is used to calculate the correct 
number of lines of text. Both of these bugs were documented in 
a recent Tech Note. 

The actual scroll routines are called from the doScroller 
procedure and simply set the control value to the new value and 
call MoveText. For the up and down button, the TrackControl 
trap calls backto the scroll upandscroll down routines continu- 
ously as long as the button is pressed. For a page scroll (clicking 
in the scroll area), the number of lines in a page is calculated from 
the current lineHeight, and the control set accordingly. If the user 
scrolls with the mouse to the window edge, an autoscroll function 
is performed which calls either scroll up or scroll down con- 
tinuously so that text can be selected beyond the window bound- 
ary. The autoscroll function routine is set up in the init procedure 
by calling SetClickLoop to associate this routine with the given 
text edit record. 

The AdjustScrollBar routine checks to see if the number of 
lines of text is greater than can be displayed in the view rectangle 
of the window. If itis then the max control is set so that the last 
page of text is visible. If not, then the max control is set to zero, 
or in otherwords, no controls are necessary. 

The ScrollChar routine moves the control to a given line in 
the text that contains the character position passed to it. The 
routine checks all the line starts in the text to find the line which 
contains that character position in the buffer. Then the control is 
set so that line position will show up in the middle of the screen 
when the text is bashed. 
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The final scroll routine is checkInsertion. This routine is the 
front end to ScrollChar and AdjustScrollBar. It calls ScrollChar 
and MoveText to do the actual scrolling. Its purpose is to scroll 
the text so that the hi-lited selection is visible. 

What is Needed 

While this program does a very good job of showing off text 
edit, it also shows off the limitations of text edit that make it 
unsuitable for the basis of a text editor. What we need now is a 
set of routines with text edit's front end (so our program won't 
haveto bere-written) but without the limitations of text size, font, 
and 32K limits. So our next step must be to re-write text edit 
without these limitations. А hard task, but needed to solve the 
problems our example program has uncovered. 

An ideal text edit library should provide for unlimited 
scrolling to any point in the text buffer, regardless of the font or 
size chosen. If the text length is below the maximum allowed, 
then that text should be displayable regardless of the font, size or 
style of the text. As we have seen, this is not the case with text edit. 

The real problem is that you would like to select fonts 
arbitrarily throughout your text. This is difficult because quick- 
draw doesn't keep track of font information. It only sets the 
current font and style and then draws to that specification. So the 
problem is to construct a record that allows quickdraw to repro- 
duce the display. Conventional text editors always used two 
bytes for each character. One byte for the character code and one 
byte for the display information. Then the font, size and style can 
be reconstructed directly from the text buffer. Text Edit saves 
only the character itself in the text buffer, nothing about how that 
character is to be displayed. Another approach is the Solo 
Approach used in the new page layout program from Mac 
America, previously called Spud. This approach placed control 
codes directly in the text buffer at the point when the text changes 
font, size or style. This might be a little more efficient than 
including a style byte for every character, but harder to imple- 
ment. À third approach would be to keep the text buffer for 
characters of text only as Text Edit does, and to add a second 
buffer that contains the format information. This might allow an 
easy way to "add on" this ability to text edit without having to re- 
write the whole thing. In the coming months, we welcome ideas 
on how these approaches might be used to expand Text Edit to a 
normal MacWrite type of editor. 

PROGRAM Mylirite; 


( This progrem is а TextEdit Demo ) 
Т by David E. Smith for MacTutor) 
I- 


SES 
ROM85, EditorGlobals, MyWriteStuff, Scrollstuff; 
PROCEDURE crash; 
BEGIN 


ExitToShell; 
END; 


PROCEDURE InitThings; 
VAR 


i, 1: integer; 
WRect : Rect; 
windtype : integer; 


Visible : boolean; 
GoAway : boolean; 
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RefVal : LongInt; TextSize( 12); 


title : str255; TextFace((]); (plain) 
stri : str255; TextMode(1); (0г) 
longi : longInt; WITH nyWindows(il^ .portRect DO 
BEGIN BEGIN 
MaxApplZone; SetRect(ViewRect, left + 4, top + 4, right 
MoreMasters; - (SBerWidth - 1), bottom - CSBarWidth - 122; 
MoreMesters; DestRect := ViewRect; 
MoreMasters; SetRect(VCRect, right - (SBerWidth - 1), 
InitGraf C@thePort); top - 1, right + 1, bottom - (SBarWidth - 2)); 
InitFonts; title := ''; 
Ini tWindows; myVControls[i] := NewControlCmyWindows[i], 
InitMenus; VCRect, title, Visible, 0, 0, Ø, ScrollBarProc, i); 
TEInit; ValidRect(VCRect); 
InitDialogs(@crash); SetRectCHCRect, left - 1, bottom - 
InitCursor; (SBarWidth - 1), right - CSBerWidth - 2), bottom + 1); 
FlushEventsCeveryEvent, 0); myHControls(i] := NewControlCmyWindowsli], 
Finished := false; HCRect, title, Visible, 8, 8, 8, ScrollBarProc, i); 
Val idRectCHCRect ); 
CR := ChrC135; END; 
BS := Chr(8); myText[i] := TENewC(DestRect, ViewRect); 
( init ny window stuff ) SetC! ikLoopC@AutoScro11, myTextlil); 
screen := ScreenBits.Bounds; (current screen device} CurrentWindow := i; (active window) 
SetRect(DragArea, Screen.left + 4, Screen. top + goodbyListli] := 0; (window is busy) 
MenuBerHeight * 4, Screen.right - 4, Screen.bottom - 42; Show indow(myW indows [1 1); 
SetRect(GrowArea, Screen.left + MinWidth, Screen.top + SelectWindow(nyWindowsLi12; 
MinHeight, Screen.right - 8, Screen.bottom - 8); END; (of i) 
SetRect(DefaultWindow, Screen.left + 30, Screen.top + END; 
50, Screen.right - 75, Screen.bottom - 75); 
SetRect(ZoomRect, Screen.left + 4, ‘Screen. top + 24, PROCEDURE SetUpMenus; 
Screen.right - 4, Screen.botton - 4); VAR 
SetRect(Cl ipBdRect, Screen. left + 100, Screen.top + i : integer; 
150, Screen.right - 100, Screen.bottom - 60); BEGIN 
FOR i := AppleMenu TO LastMenu DO 
RefVel := 0; BEGIN 
title := ‘Clipboard’; myMenus[i] := GetMenuCi); 
ClipBdWindow := Мени іпаоисесл ipBdStorage, ClipBdRect, Inser tMenuCnyMenus[i], 0); 
title, False, rDocProc, pointer(-1), true, RefVal); END; (of i) 
SetPortCClipBdWindow); AddResMenu(CmyMenus(AppleMenu], 'DRVR'); 
Tex tFont(systemFont); AddResMenuCmyMenus [FontMenul, ‘FONT'); 
TextSize( 12); DrewMenuBar ; 
TextFaceCL 12; (plein) UpdateMenus; 
TextModeC 1); (0r) END; (of proc) 
m | каше .portRect 00 
SetRect(ViewRect, left + 4, top + 4, right - қышы doMouse (myEvent : EventRecord); 
(SBarWidth - 1), bottom - (SBarWidth + 10); whereIsIt : integer; 
DestRect := ViewRect; whichWindow : WindowPtr; 
END; localPt, globalPt : Point; 
ClipBdText := TENew(DestRect, ViewRect); oldPort : GrefPtr; 
IF TEFronScre © noErr THEN BEGIN 

BEGIN (Desk Scrap to TEScrep) globalPt := myEvent.where; 

END; | localPt := globalPt; (global coord of mouse) 
ClipBdText^^.hText := TEScrepHendle; (TEto Clip) GlobalToLocal(localPt); (local coord of mouse) 
ClipBdText**.teLength := TEGetScrepLen; whereIsIt := FindWindow(globalPt, whichWindow); 
TECalText(Cl ipBdText); CASE wherelIsIt OF 

inDesk : (0) 
Visible := false; BEGIN 
windtype := documentProc + ZoomBox; END; 
GoAway := true; inMenuBer : (1) 
FOR i := 1 TO MaxWindows DO doMenuBar (MenuSelect(CglobslPt22; 
BEGIN | inSysWindow : (2) 
RefVal := i; SystemClick(myEvent, whichWindow); 
j:* G - D * 18; inContent : 3 
longi := longInt(Ci); doContent(myEvent, whichWindow); 
NumToStringClongi, stri); inDrag : 4 
title := concatC'Untitled ', ‘Window ', stri); doDrag(whichWindow, globalPt); 
SetRect(WRect, DefaultWindow.left + j, inGrow : 5 
DefaultWindow.top + j, DefeultWindow.right + J, doGrow(whichWindow, globalPt, False); 
DefaultWindow.bottom + J); inGoAway : (6) 


myWindows[i] := NewWindowC(NIL, WRect, title, 
Visible, windtype, pointer(-1), GoAway, RefVal); 

SetPor tCmyWindows[i}); 

Tex tFont(systemF ont ); 
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IF TrackGoAway(whichWindow, globalPt) THEN 
doC loseW indow( wh ichwW indow); 
inZoomIn, InZoomOut : (7, 8) 
BEGIN 
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IF TrackBoxCwhichWindow, globalPt, whereIsIt) 
EN 


BEGIN 
GetPort(OldPort); 
SetPort(whichWindow); (safety device) 


ZoomWindow(whichWindow, whereIsIt, True); 


doGrow(whichWindow, globalPt, True); 
SetPor t(01dPort); 
END; 


END; 
OTHERWISE 
BEGIN 


END; 
END; (of whereIsIt) 
END; 


PROCEDURE doKeyDowns (myEvent : EventRecord); 
VAR 
ch : cher; 
charCode : longInt; 
keyCode : longInt; 
BEGIN 
charCode := BitAnd(myEvent Message, charCodeMask); 
keyCode := BitAnd(myEvent.Message, keyCodeMask); 
:= Chr(charCode); (get keyboard char) 
IF Bi tAnd(myEvent .Modif і iers, CmdKey) = CmdKey THEN 
doMenuBar (MenuKey(ch)) ( do menu command key) 


LSE 
BEGIN ( do keystroke ) 
IF currentWindow = 0 THEN 
Sysbeep(5) (no typing in clipboard ) 
ELSE IF nyWindowslcurrentWindow] О 
FrontWindow THEN 
Sysbeep(5) (error) 
ELSE IF CmyText(currentWindow]**.teLength = 
MaxInt) AND (ch «€» BS) THEN 
SysBeep(5) 


BEGIN (type in active text window) 
TEKeyCch, myText[currentWindow1); 
AdjustScrollBar(currentW indow2; 
CheckInsertionCcurrentWindow); 
END; (of TEKey stuff) 
END; (of else key stroke ) 
END; (of proc) 


PROCEDURE doUpdates (myEvent : EventRecord); 
VAR 


1: integer; 
UpdateWindow, TempPort : WindowPtr; 
BEGIN 
UpdateWindow := WindowPtr(myEvent .message); 


IF UpdateWindow = ClipBdWindow THEN 
BEGIN 
GetPort(TempPort); (save port) 
SetPor t(C1 ipBdWindow); 
Beg inUpDate(C1 ipBdW indow); 
EraseRect(Cl ipBdWindow* .visRgn**.rgnBBox ); 
TEUpdate(C 1 ipBdW indow* .visRgn** .rgnBBox, 
ClipBdText); 
EndUpDate(Cl ipBdWindow); 
: SetPort(TempPort); (restore port) 
ND; 
FOR i := 1 TO MaxWindows DO 
BEGIN 


IF UpdateWindow = myWindows(i] THEN 
BEGIN 
GetPort(TempPort); (save port) 
SetPor t(nyW indowsL i1); 
BeginUpDateCmyWindows[i 1); 
EraseRect (nyWindows[i 1“ .por tRect); 
( clear update region) 

DrawControls(myWindowsli 10; 
DrawGrowIcon(ngWindows[i 1; 
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TEUpdeteCnyW indows( 11^ . visRgn^^ .rgnBBox, 
nyText[ i12; 
EndUpDateCnyN indows[i 10; 
SetPortCTempPort); 
END; (of if then) 
END; (of i loop) 
END; (of proc) 


PROCEDURE doActivates (myEvent : EventRecord); 
VAR 


i: integer; 
TergetWindow : WindowPtr; 
BEGIN 
TergetWindow := WindowPtr(myEvent . message); 


IF Odd(myEvent.modifiers) THEN 
BEGIN (activate) 
FOR i := 1 ТО MexWindows 00 
BEGIN 
IF TergetWindow = myWindows[i] THEN 
BEGIN 
SetPortCTargetWindow); 
UpdeteMenus; 
DrewGrowIcon(myWindows[i1); 
TEActivateCnyText[ i12; 
Showcontrol(myVControlsli)); 
ShowControlCnyHControlsLi 1); 
currentWindow := i; 
END ( of my window activation} 
ELSE IF TergetWindow = ClipBdWindow 
N 


BEGIN 
IF TEFromScrep ©› noErr THEN 
BEGIN (геәд desk scrap) 
END; 
currentWindow := 9; 
ClipBdText^^.teLength := TEGetScrepLen; 
TECal Text(ClipBdText); 
InvelRectCClipBdText^^ .viewRect); 
END; 
END; ( of i loop) 
END (of activate loop} 


E 
get p e 
BECA TO MaxWindows DO 


IF TargetWindow = myWindowsti] THEN 
BEGIN 
DrewGrowIcon(nyWindows[i]1); 
TEDeact ivateCmyText Li J); 
HideControl(CmyVControlslil); 
HideControl(nyHControls[i12; 
END; ( of my window activation) 
END; ( of i 1бор} 
END; (of deactivate loop) 
END; (of proc) 


PROCEDURE doSwitcher (myEvent : EventRecord); 
VAR 


SwitchInfo : LongInt; 
bit® : LongInt; 
bit1 : LongInt; 
BEGIN (we use the desk screp so no need) 
SwitchInfo := myEvent.message; 
bit® := 31; (convert 68000 to toolbox) 
biti := 30; 
IF BitTstCeSwitchInfo, bit?) = TRUE THEN 
BEGIN (resume) 
IF BitTstC@SwitchInfo, biti) = TRUE THEN 
BEGIN (convert clipboard) 
END; 


BEGIN (suspend) 
IF BitTstCeSwitchInfo, bit1) = TRUE THEN 
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BEGIN (convert clipboard) 
END; 
END; 
END; 


PROCEDURE MainEventLoop; 
CONST 


SwitcherEvt = 15; 

VAR 
Event : EventRecord; 
DoIt : Boolean; 

BEGIN 

REPEAT 
SystemTask ; 
IF currentWindow © 0 THEN 

TEIdleCnyText [currentW indow 1); 
DoIt := GetNextEventCEveryEvent, Event); 
IF DoIt THEN 

CASE Event.what OF 

nouseDown : 
doMouse(Event); 
KeyDown, Autokey : 
doKeyDowns(Event); 
updateEvt : 
doUpdates(Event); 
activateEvt : 
doActivates(Event); 
SwitcherEvt : 
doSwitcher(Event); (event 15) 
OTHERWISE 
BEGIN 
END; 

END; (of event case) 
unLoadSeg(@doScrollers); (ScrollStuff unit) 
unLoadSeg(@doGrow); (myWrite Stuff unit ) 

UNTIL Finished; (end program} 
IF TEGetScrapLen > 0 THEN 
BEGI 
:= ZeroScrap; 
TEToScrap; 


END; 


BEGIN (main program) 
InitThings; 
SetUpMenus; 
MainEventLoop; 

END. 


UNIT EditorGlobals; 
INTERFACE 

( Global Constants ) 

CONST 

(memory management stuff) 
MaxLines = 65535; 

(quickdraw stuff} 
sizelimit = 128; 

(window constants) 
maxWindows = 4; 
ZoomBox = 8; (window type) 
MinWidth = 80; 
MinHeight = 80; 
MenuBarHeight = 20; 

(dialog stuff} 
otherItem = 3; 

( menu res id's) 
AppleMenu = 256; 
FileMenu = 257; 
EditMenu = 258; 
SearchMenu = 259; 
FormatMenu = 268; 
FontMenu = 261; 
SizeMenu = 262; 
StyleMenu = 263; 
ModeMenu = 264; 
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TransferMenu = 265; 
LastMenu = TransferMenu; 


(menu items) 


eAbout = 1; 
fNew = 1; 
fOpen = 2; 
fClose = 3; 
fSave = 4; 
fSaveAs = 5; 
fPageSet = 6; 
fPrint = 7; 
fQuit = 9; 
eUndo = 1; 
eCut = 3; 
eCopy = 4; 
ePaste = 5; 
eClear = 6; 
eSelAll = 8; 
eClipboard = 9; 
sPlain = 1; 
sBold = 2; 
sItalic = 3; 


sUnderline = 4; 
sOutline = 5; 
sShadow = 6; 
sCondense = 7; 
sExtend = 8; 
sLeft = 10; 
sCenter = 11; 
sRight = 12; 
Style2Items = 4; 
mor = 1; 


(controls stuff) 
active = £; 
inactive = 255; 
sbarwidth = 16; 


( Global Variables ) 
VAR 


(ny misc stuff) 
Finished : boolean; 
CR : char; 
BS : char; 

(nenu stuff) 

myMenus : ARRAY([AppleMenu..LastMenu] OF MenuHandle; 

LestJust : integer; (current text rec) 
LastFont : integer; ^ (current port) 
LastStyle : Style; (current port) 
LastSize : integer; ^ (current port) 
LestMode : integer; ^ (current port) 
LastmFont : integer; (menu item) 
LestmStyle : integer; (menu item) 
LestmSize : integer; (menu item) 
LestmMode : integer; (menu item) 
LestmJust : integer; (menu item) 

(window stuff) 
ClipBdWindow : Windowptr; 
ClipBdStorage : WindowRecord; 
ClipBdRect : Rect; 
ClipBdText : TEHendle; 
myWindows : ARRAY[1..MaxWindows] OF Windowptr; 


currentWindow : integer; {index to active window) 


GoodbyList : ARRAY[1..MaxWindows] OF Integer; 
DragArea : Rect; 
GrowArea : Rect; 
Screen : Rect; 
DefaultWindow : Rect; 
ZoomRect : Rect; 
(scrollers stuff) 
myVControls : ARRAY[1..MaxWindows] OF ControlHendle; 
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myHControls : ARRAY[1..MaxWindows] OF ControlHandle; 
HCRect, VCRect, GrowRect : Rect; 

(text edit stuff) 
myText : ARRAY[1..MexWindowsl OF TEHandle; 
DestRect : Rect; 
ViewRect : Rect; 
dummy : LongInt; (TEScrep ver) 

END ck 


UNIT ScroliStuff; 
INTERFACE 


USES 
ROM85, EditorGlobals; 


PROCEDURE AdjustScrollBar CHandleIndex : integer); 
PROCEDURE 5сго11Сһаг CHendleIndex : integer; charPos : 
integer; toBottom : boolean); 

PROCEDURE CheckInsertion CHandleIndex : integer); 
PROCEDURE doScrollers CHandleIndex : integer; scrollBar : 
ControlHandle; part : integer; localMouse : point); 
FUNCTION AutoScroll : boolean; 


IMPLEMENTATION 
FUNCTION Sign CLongvar : Longint) : integer; 
BEGIN 

IF Longver >= Ø THEN 


sign := 1 
ELSE IF Longver < 0 THEN 
sign := -1; 


END; 


FUNCTION LinesInText (HandleIndex : integer) : integer; 
( Fix text edit bug for cr at end of text ) 
VAR 
і: integer; 
lines : integer; 
texthandle : CharsHandle; 
BEGIN 
i := HendleIndex; 
WITH myTextlil** DO 
BEGIN 
lines := nLines; 
texthendle := CharsHendle(ChText); 
IF teLength » 0 THEN 
IF texthendle^^[teLength - 1] = CR THEN 
lines := lines + 1; 
LinesInText := lines 


END; 
PROCEDURE MoveText CHandleIndex : integer); 
VAR 


ViewTop, DestTop : LongInt; 
scrollvalue : LongInt; 
height : integer; 
i, j : integer; 
scrolldiff : longInt; 
oldScroll : longInt; 
newScroll : longInt; 

BEGIN 
i := HendleIndex; 
ViewTop := myText[i]^^.ViewRect.top; 
DestTop := myTextlil**.DestRect. top; 
oldScroll := LongInt(ViewTop - DestTop); 
scrollvalue := GetCtlValue(myVControls[i1); 
height := myText[i]^^.lineHeight; 
newScroll := LongIntCscrollvalue * Height); 
scrolldiff := LongIntColdscroll - пежѕсго11); 
IF abs(scrolldiff) » 32000 THEN 


EGIN 
TEScro11C0, sign(scrolldiff) * 32000, 
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nyText[ i12; 
sysbeep(5); (Text Edit Limitation!) 


LSE 
BEGIN 
IF Cscrolldiff © 0) THEN 
TEScro11(0, scrolldiff, myTextlil); 
(vertical - ws bug ТМ822) 
E . 


д 
END; 


PROCEDURE scroll.up CtheControl : controlHandle; 
pertCode : integer); 


VAR 
newValue : integer; 

BEGIN 
newValue := GetCtlValueCtheControl) - 1; 
SetCtlValueCtheControl, newValue); 
moveTextCcurrentWindow); 

END; 


PROCEDURE scroll.down (theControl : controlHandle; 
pertCode : integer); 


VAR 
newValue : integer; 

BEGIN 
newValue :* GetCtlValueCtheControl2) + 1; 
SetCtlValueCtheControl, newValue); 
noveText(CcurrentWindow); 

END; 


PROCEDURE page-scroll (part : integer; 
scrollBar : ControlHandle; 
direction : integer); 
VAR 
newValue : integer; 
page : integer; 
BEGIN 
WITH myText(currentWindow]^^, viewRect DO 
T page := direction * CCbottom - top) DIV lineHeight - 
newValue := GetCtlValueCscrollBar) + page; 
SetCtlVelue(CscrollBer, newValue); 
moveTextCcurrentWindow); 
END; 


PROCEDURE AdjustScrollBar; (CHandleIndex: integer )) 
VAR 


WindowLInes : integer; 
i : integer; 
currentLines : integer; 
BEGIN 
i := HendleIndex; 
WITH myText(ilJ^* DO 
WindowLines := ((ViewRect.bottom - ViewRect.top) DIV 
lineHeight); 
currentLines := LinesInTextCi); 
IF currentLines >= WindowLines THEN 
SetCtlMaxCnyVControls(i], currentLines - WindowLines) 
ELSE 
SetCtlMaxCmyVControlslil, 02 
END; 


PROCEDURE 5сго11Сћаг; (CHandleIndex : integer; ) 
(charPos : integer; } 
(toBottom : boolean); } 


VAR 
i: integer; 
theLine : integer; 
WindowLines : integer; 
BEGIN 


i := HandleIndex; 
theLine := 0; 
WITH nyTexttiJ^^ DO 


209 


WHILE lineStarts[(theLine + 1) <= CharPos 00 

theLine := theLine + 1; 
IF toBottom THEN 

BEGIN 

WITH nyTexttil^^ DO 
windowLines := (viewRect.bottom - 
viewRect.top) DIV lineheight; 

theLine := theLine - (windowLines - 1); 


END; 
setCtlValue(nyVControls(il, theLine); 
MoveTextCi); 
END; 
ашы checkInsertion; (CHandleIndex : integer) 
А 
i : integer; 
topline : integer; 
bottomline : integer; 
WindowLines : integer; 
BEGIN 


i := HendleIndex; 
WITH nyTexttil^^ DO 
WindowLines := (ViewRect.bottom - ViewRect.top) DIV 
lineHe ight; 
topline := GetCtlValueCnyVControls[ i12; 
bottomline := topLine + WindowLines; 
WITH myTextlil** DO 
IF GetCtlMax(CmyVControls(i]) = Ø THEN 
MoveText(Ci) 
ELSE IF selEnd ‹ lineStarts[topLine] THEN 
ScrollChar(i, selStart, False) 
ELSE IF selStart >= lineStarts[bottomL ine] THEN 
ScrollCharCi, selEnd, true); 


END; 
PROCEDURE doScrollers; (HendleIndex: integer) 
(scrollBar : ControlHandle) 
(pert : integer) 
(localMouse : point?) 
VAR 
result : integer; 
i: integer; 
BEGIN 
i := HendleIndex; 
CASE pert OF 
inUpButton : 
result := TreckControlCscrollbar, localMouse, 
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6scroll.up); 


inDownButton : 
result := TreckControl(scrollber, localMouse, 


@ѕсго11_доип); 


inPageUp : 
pege-scrollCpart, scrollBar, -1); 
inPageDown : 
pege-scroll(part, scrollBar, 1); 
inThumb : 
BEGIN 
result := TreckControl(scrollBar, localMouse, NIL); 
moveTextCi); 


OTHERWISE 
BEGIN 
END; 


END; (of case) 
END; (of proc} 


FUNCTION AutoScroll; (:boolean;} 
VAR 


BEGIN 


END; 


result : boolean; 
oldClip : RgnHendle; 
mouseloc : point; 
TextRect : rect; 

i : integer; 

control : controlHandle; 


i := currentWindow; 

result := true; 

oldClip := NewRgn; 

GetClipColdClip); 

ClipRect(myWindows[i]*.portRect); 

Ge tMouse(mouseLoc); 

TextRect := myText[i]^^.viewRect; 

Control := myVControlslil]; 

IF mouseLoc.v « TextRect.top THEN 
Scroll.UpCControl, InUpButton) 

ELSE IF mouseloc.v › TextRect.bottom THEN 
Scroll.DownCControl, InDownButton); 

SetClipColdClip); 

DisposeRgn(oldClip); 

AutoScroll := result; 


END. (of unit) 
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UNIT ayWriteStuff; 
INTERFACE 


ES 
ROM85, EditorGlobals, ScrollStuff; 


PROCEDURE UpdateMenus; 
PROCEDURE UpdateFonts; 
PROCEDURE UpdateSize; 
PROCEDURE UpdateStyle; 
PROCEDURE UpdateuJust ; 
PROCEDURE UpdateMode; 
PROCEDURE ShowFonts (FontNum : integer); 
PROCEDURE doCloseWindow CgoodbyWindow : 
PROCEDURE doAbout; 
PROCEDURE doNewW indow j 
PROCEDURE doMenuber (menuResult 
PROCEDURE doContent (ConEvent : 
contentWindow : windowPtr); 
PROCEDURE doDrag (GrabWindow : 
GlobalMouse : point); 
PROCEDURE doGrow (ResizeWindow 
Globalmouse : point; Zoomf lg 


IMPLEMENTATION 


PROCEDURE BashText; 
VAR 
FontIRec : 
Height : integer; (calculated new lineheight) 
CherPos : integer; 
ControlLine : integer; 
IN 


windowPtr ); 


: LongInt); 
EventRecord; 


WindowPtr ; 


: WindowPtr; 
: Boolean); 


FontInfo; 


SetPort(myWindowstcurrentWindow1); 
GetFontInfoC(FontIRec); (from current graf port) 
nyText[currentWindow]^^. txFont := thePort^.txFont; 
nyText[currentWindowl^^.txFace := thePort^.txFace; 
myText[currentWindow]^^.txMode := thePort^.txMode; 
myText[currentWindowl^^.txSize := thePort^.txSize; 
nyText[currentWindow]"^. fontAscent : :* FontIRec. ascent; 
Height := FontIRec.ascent + Font IRec. descent + 
Font IRec. leading; 
nyText[currentWindow]^^. lineHeight := Height; 
nyText[currentWindow]^^ .just := LastJust; 
ControlLine :- GetCtlValueCnyHControls currenti indow2; 
CherPos := myText([currentWindowl^^.lineStarts[ Con- 
trolLine]; 
TECalText(myText [currentWindow12; 
InvalRect(myText [currenti indow]^*. ViewRect); 
AdjustScro] 1Bar(CcurrentWindow); 
ScrollCharCcurrentWindow, CharPos, False); 
Check Inser t ionCcurrentW indow); 
END; 
ur doFonts CfontNo : integer); 
FontNumber : integer; 
FontName : Str255; 
BEGIN 
IF currentWindow © Ø THEN 
BEGIN 
getI temCmyMenus[FontMenu], fontNo, FontName); 
GetFNum(FontName, FontNumber); 
SetPor t (myWindows[currentW indow)); 
TextFont(FontNumber); (change port's font) 
UpdateFonts; (update menu) 


BashText; (update window) 
END; 
END; 
PROCEDURE doSize (sizeNo : integer); 
CONST 


DialogID = 129; (other dialog) 
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VAR 


sizeNunber 
sizeNum : integer; 
sizeName : Str255; 
SizeCount : integer; 
dialogP : DialogPtr; 
item : integer; 
dtype : integer; 
ditem : handle; 
drect : rect; 

dtext : Str255; 
ectiveSize : integer; 
LongSize : LongInt; 
sizeStr : Str255; 


: LongInt; 


BEGIN 


IF currentWindow <> 0 THEN 
BEGIN 
SizeCount := (CountMItems(myMenus[SizeMenu1)) - 2; 
IF (sizeNo <= SizeCount) AND CsizeNo > Ø) THEN 
BEGIN 
GetItem(nyMenus[SizeMenul, sizeNo, sizeNeme); 
Str ingToNum(sizeName, sizeNunber); 
sizeNum := LoWord(sizeNumber ); 
SetPor t(myWindows[currentWindow 1); 
TextSizeCsizeNum); {change port's text size) 
UpdateSize; 
BeshText; 
END; (of sizeno) 


IF sizeNo = SizeCount + 2 THEN 

BEGIN (do other) 
activeSize := thePort*.txSize; 
LongSize := LongIntCactiveSize); 
NumToStringCLongSize, sizeStr); 
PeremText(sizeStr, '', '', ''); 
dialogP := GetNewDialog(DialoglD, NIL, pointer(- 


1)); 


ModalDialog(NIL, item); 

GetDItemCdialogP, otherIten, dtype, ditem, drect); 
GetITextCditem, dtext); 

StringToNumCdtext, LongS ize); 

sizeNum := LoWord(LongSize); 
DisposDialog(dialogP); 


IF (sizeNum > 0) AND CsizeNum < sizelimit) THEN 

BEGIN 
Se tPor tCmyW indows [currentWindow12; 
TextSizeCsizeNum); (change port's text size) 
UpdateSize; 
BashText; 

END 

ELSE 
sysbeep(5); (size too big) 

END; (of other) 
END; (of currentWindow 90) 


END; (of proc) 


PROCEDURE doStyle (StyleNo : integer); 
VAR 

NewStyle : Style; 
BEGIN 

IF currentWindow «» 0 THEN 

BEGIN 


IF nyWindows[currentWindow] = FrontWindow THEN 
BEGIN 

SetPor t(myWindows(currentWindow]); 

NewStyle := ГІ; 

CASE StyleNo OF 


sLeft : 

nyText[currentWindowl^^.just := teJustLeft; 
sCenter : 

nyText[currentWindow]^^.just := teJustCenter; 
sRight : 


nyText [currentW indow]1^* . just :* teJustRight; 
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NewStyle := [bold]; 


p 
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[italic]; 


= 
@ 
= 
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ce 
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(under ine]; 


NewStyle := [outline]; 


NewStyle := [shadow]; 
END; 


p 
@Ф 
= 
e 
e 
< 
— 
eo 
и 


[condense]; 


=z 
@ 
Ж 
с 
e 
< 
— 
@ 
u 


[extend]; 
END; 

OTHERWISE 
BEGIN 
END; 

END; (of cese) 


IF NewStyle <= thePort^.txFace THEN 
textfaceCthePort^.txFace - NewStyle) 


ELSE 


textface( thePort*.txFace + NewStyle); 


UpdateJust; 
UpdateStyle; 
BashText; 
END; (of currentWindow) 
END; (of frontwindow) 
END; (of proc) 


PROCEDURE doMode (ModeNo : integer); 
BEGIN 
IF currentWindow © 2 THEN 
BEGIN 


SetPor tCmyW indows [currentWindow 12; 
Тех tMode(ModeNo); 

UpdateMode ; 

BashText; 

END; 
END; 


PROCEDURE UpdateMenus; 
BEGIN 
UpdateFonts; 
UpdateSize; 
UpdateStyle; 
UPdateJust; 
UpdateMode; 
END; 


PROCEDURE UpdeteFonts; 
VAR 


i : integer; 
FontCount : integer; 
FontNumber : integer; 
activeFont : Str255; 
FontName : Str255; 
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BEGIN 


GetFontNemeCthePort^.txFont, activeFont); 
FontCount := CountMItems(myMenus [FontMenu 1); 
FOR i := 1 TO FontCount DO. 

BEGIN 


GetItenCmyMenus(FontMenul, i, FontName); 


IF (FontName = activeFont) THEN 
BEGIN 


CheckItem(myMenus [FontMenu)J, LastmFont, false); 
CheckItem(nyMenus[FontMenul], i, true); 


LastmFont := i; 
GetFNumCFontName, FontNumber ); 
LastFont := FontNumber ; 
ShowF onts(LastFont); 
END; (of if then} 
END; (of i loop) 


END; 
PROCEDURE UpdateSize; 
VAR 


sizeCount : integer; 
sizeNumber : LongInt; 
sizeNum : integer; 
activeSize : integer; 
sizeName : Str255; 
1: integer; 

doneflg : boolean; 


BEGIN 


doneflg := false; 
activeSize := thePort^.txSize; 


SizeCount := C(CountMItems(myMenus[SizeMenu1)) - 2; 


FOR i := 1 TO SizeCount 00 

BEGIN 
GetItem(myMenus[SizeMenul, i, sizeName); 
StringToNum(sizeName, sizeNumber ); 
sizeNum := LoWord(sizeNumber); 
IF (sizeNum = activeSize) THEN 
BEGIN 


CheckItemCmyMenus[SizeMenu], LastmSize, false); 


CheckI temCmyMenus[SizeMenu], i, true); 
LastmSize := i; 
LastSize := sizeNum; 
doneflg := true; 
END; (of if then) 
END; (оғ i loop) 


IF doneflg = false THEN 


BEGIN (do other} 


IF CactiveSize > Ø) AND CactiveSize < sizelimit) THEN 


BEGIN 


CheckItemCnyMenus[SizeMenul, LestmSize, false); 
CheckI temCmyMenus[SizeMenu], SizeCount + 2, true); 


LastmSize := SizeCount + 2; 
LastSize := activeSize; 
END; 


END; 
END; (of proc} 


PROCEDURE UpdateStyle; 
VAR 
i, j : integer; 
StyleCount : integer; 
activeStyle : Style; 
MenuStyle : Style; 
BEGIN 


StyleCount := (CountMItemsCmyMenus[StyleMenul) - 


Style2I tems); 
activeStyle := thePort*.txFace; 
FOR i := 1 TO StyleCount 00 
BEGIN 
CASE i OF 
1 " 


_ MenuStyle := ПІ; 
2 
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MenuStyle := [bold]; 


“a MenuStyle := [italic]; 

Е MenuStyle := [underline]; 

= MenuStyle := [outline]; 

i MenuStyle := [shadow]; 

т: MenuStyle := [condense]; 

a MenuStyle := [extend]; 
OTHERWISE 


MenuStyle : 
END; (of cese i) 


[1]; 


IF ((MenuStyle <= activeStyle) AND (MenuStyle © [])) 
THEN 


BEGIN 
CheckItem(nyMenus[StyleMenu], i, true); 
CheckI temCmyMenus[StyleMenu], 1, false); 
LastmStyle := i; 
LastStyle := activeStyle; 
ND 


ELSE IF activeStyle = (] THEN 

BEGIN 

Check I temCmyMenus[StyleMenu], 1, true); 

FOR j := 2 TO StyleCount DO 
BEGIN 
CheckI temCmyMenus[StyleMenu], j, false); 
END; (of j loop) 

LastmStyle := 1; 

LastStyle := activeStyle; 

END ( of (1) 

LSE 


BEGIN 
Check I temCmyMenus[StyleMenu], i, false); 
END; 
END; (of i loop) 
END; 
PROCEDURE UpdeteJust ; 
VAR 
i : integer; 
ectiveJust : integer; 
BEGIN 
IF currentWindow © 0 THEN 
BEGIN 
IF myWindows[currentWindow] = FrontWindow THEN 
BEGIN 
1 := CCountMI temsCmyMenus(StyleMenu]) - 
Style2I tems); 
CASE Lastuust ОҒ 
teJustLeft : 
CheckI temCmyMenus[StyleMenu], i + 2, false); 
teJustCenter : 
CheckI temCmyMenus[StyleMenu], i + 3, false); 
teJustRight : 
CheckI temCmyMenus[StyleMenu], i + 4, false); 
OTHERWISE 
BEGIN 


END; 
END; (of case) 


&ctiveJust := myText[currentWindow]^* . just; 
LestJust := activeJust; 
CASE activeJust OF 
teJustLeft : 
BEGIN 
CheckItemCnyMenus[StyleMenul, i + 2, true); 
LastmJust := i + 2; 
END; 
teJustCenter : 
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BEGIN 
Check I tem(myMenus[StyleMenu], i + 3, true); 
LastmJust := i + 3; 
END; 
teJustRight : 
BEGIN 
Check I tem(myMenus[StyleMenu], i + 4, true); 
LastmJust := 1 + 4; 


END; 
OTHERWISE 
BEGIN 
END; 
END; (of case} 
END; 
END; 


END; 
PROCEDURE UpdateMode; 
VAR 


activeMode : integer; 
GIN 


activeMode := thePort^.txMode; 

CheckI temCmyMenus[ModeMenu], LastmMode, false); 
CASE activeMode OF 

1: 


BEGIN 

CheckItem(myMenus [ModeMenu], 1, true); 
LastmMode := 1; 

END; 


BEGIN 

CheckItemCmyMenus [ModeMenul, 2, true); 
LastmMode := 2; 

END; 


BEGIN 
CheckItemCmyMenus (ModeMenul, 3, true); 
LestmMode := 3; 
END; 
OTHERWISE 
BEGIN 
END; 
END; ( of cese) 


LestMode := activeMode; 
END; 


PROCEDURE ShowFonts; ((FontNum : integer);) 
VAR 


i : integer; 

sizeStr : Str255; 

sizeNum : LongInt; 

BEGIN 

FOR i := 1 TO CCountMItemsCmyMenus[sizeMenul) - 2) DO 

BEGIN 
GetItem(myMenus[sizeMenul, i, sizeStr); 
StringToNum(sizeStr, sizeNum); 
IF RealFont(FontNum, sizeNum) THEN 

Қада i, (Outline]) 


SetItemStyleC(myMenus(sizeMenul, i, (1); 
END; (of i) 
END; (of proc) 


we doCloseWindow; (CgoodbyWindow : windowPtr) 
AR 


їі: integer; 

BEGIN 

HideWindow(goodbyW indow); 

CurrentWindow := 0; 

FOR i := 1 TO MaxWindows 00 

BEGIN 
IF goodbyWindow = myWindows[i] THEN 
BEGIN 


goodbyList[i] := i; 
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END; END; 


END; fOpen : 
END; BEGIN 
END; 
PROCEDURE doAbout; fClose : 
CONST BEGIN 
DialogID = 128; IF currentWindow «> 0 THEN 
VAR IF myWindows(currentWindow] = FrontWindow THEN 
dielogP : DislogPtr; doC loseW indowCmyW indows [currentW indow 10; 
item : integer; END; 
BEGIN fSave : 
dialogP := GetNewDialog(DialogID, NIL, pointer(-1)); BEGIN 
ModalDialog(NIL, item); END; 
DisposDialog(dialogP ); fSaveAs : 
END; BEGIN 
END; 
PROCEDURE doNewW indow; fPageSet : 
VAR BEGIN 
і : integer; END; 
doneflg : boolean; fPrint : 
BEGIN BEGIN 
doneflg := false; END; 
FOR i := 1 TO MaxWindows DO fQuit : 
BEGIN BEGIN 
IF doneflg = false THEN FOR i := 1 TO MaxWindows DO 
BEGIN BEGIN 
IF goodbyList[i]l = i THEN DisposeControl(myVControlsli]); 
BEGIN (window is free) DisposeContro!(myHControlsti 12; 
CurrentWindow := i; TEDispose(nyText [ i12; 
SetPor t (my indows[CurrentWindow]12; DisposeWindow(myWindowsLi 1); 
UpdateMenus; END; 
goodbyL ist[i] := 0; Finished := true; 
doneflg := true; END; 
TESetSelectC0, MaxLines, myText[i12; OTHERWISE 
TEDeleteCnyText i12; BEGIN 
ShowWindowCmyWindowsLi 12; END; 
SelectWindow(myNindowsti 12; END; (of theiten) 
AdjustScrollBar(Ci); END; (of FileMenu) 
CheckInsertion(i); EditMenu : 
END; (of free window stuff) BEGIN 
END; (of if donefig) IF NOT SystemEdit(theitem - 1) THEN 
END; (of for i loop) BEGIN 
IF doneflg = false THEN ipii theIten OF 
sysBeep(5); (no windows left} BEGIN 
END; (of proc) sysbeep(5); 
AN aatia doMenuber; ((menuResult : LongInt)) a 
BEGIN 
theMenu : integer; | 
theltem : integer; IF нк o 0 THEN 
ies шы, ; CheckInsertionCcurrentWindow); 
17 т = Mer) TECutCmyText [currentWindow]); 
BEGIN nteger, AdjustScrol1Bar(currentWindow); 
_ CheckInsertionCcurrentWindow); 
theMenu := HiWord(menuResult); (menu) Чак. <= 7его5сгар: 
thelten := LoWord(menuResult); (item) duse) (= TETOS ap. 
Appl eMenu : ELSE 
"E Кы sysbeep(5); 
eltem = eAbout THEN END: 
doAbout eCopy 2 
EE BEGIN 
GetItem(nyMenus[AppleMenul, theItem, daName); IF u © 0 THEN 
accItem := OpenDeskAcc(daName), Check Insert ion(currentW indow); 
END; (else) TECopy(myText[currentWindow]); 
END; (of AppleMenu) dummy := ZeroScrap; 
FileMenu : dummy := TEToScrep; 
BEGIN END 
CASE іһе еп ОҒ ELSE 
du sysbeep(5); 
BEGIN. END; 5 
doNewW indow; ePaste : 
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BEGIN 
IF currentWindow «» 8 THEN 
BEGIN 
IF TEFromScrap © noErr THEN 
BEGIN (Desk Scrap to ТЕ5сгар) 


END; 
IF (myText [currentW indow ^^ . teLength * 
TEGetScrapLen) > MexInt THEN 
SysBeep(5) 
LSE 


BEGIN 
CheckInsertionCcurrentWindow); 
TEPeste(nyText [currentWindow1); 
AdjustScrollBarCcurrentWindow); 
CheckInsertionCcurrentWindow); 
END; ( of else) 

END 


ELSE 
sysbeep(5); 
END; ( of peste) 
eClear : 

BEGIN 

IF currentWindow © 0 THEN 
BEGIN 
CheckInsertionCcurrentWindow); 
TEDe Te teCmyText [currenti indow]); 
AdjustScrollBar(CcurrentW indow); 
CheckInsertionCcurrentWindow); 

ND 


ELSE 
Sysbeep(5); 


eSelAll : 

BEGIN 

IF currentWindow © Ø THEN 
BEGIN 
TESetSelectC0, MaxLines, 

nyText [currentWindow12; 

TECopy(myText [currentWindow 1); 
dummy := ZeroScrap; 
dummy := TEToScrap; 
END 

ELSE 
sysbeep(5); 


eClipboard : 
BEGIN 
currentWindow := 9; 
SetPortCC1ipBdW indow); 
ShowWindowCClipBdWindow); 
SelectWindowCClipBdWindow); 
UpdateMenus; 
END; 
OTHERWISE (no menu items selected) 
BEGIN 
END; 
END; (of іһе еп) 
END; (of if then) 
END; (of EditMenu) 
SearchMenu i 
BEGIN 
END; 
FormatMenu : 


doFontsCtheItem); 
S izeMenu 
BEGIN 
doSizeCtheItem); 


StyleMenu 
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BEGIN 
doStyleCtheItem); 


7 
ModeMenu : 
BEGIN 
doModeCtheItem); 
TrensferMenu : 
BEGIN 
END; 
OTHERWISE 
BEGIN 
END; 
END; (of theMenu) 
HiliteMenu(20);  (un-hilite selected menu) 
END; 


PROCEDURE doContent; ((ConEvent : EventRecord) 
(contentWindow : windowPtr);) 
VAR 


localPt, globalPt : Point; 
pert : integer; 
control : ControlHandle; 
i : integer; 
BEGIN 
IF contentWindow © FrontWindow THEN 
SelectWindowCcontentWindow); 
globalPt := ConEvent . where; 
localPt := globalPt; (global coord of mouse) 
GlobalToLocalClocalPt); (оса! coord of mouse) 
part :- FindControlClocalPt, contentWindow, control); 


IF contentWindow = ClipBdWindow THEN 
BEGIN 
currentWindow := 0; 
SetPor t(C1 ipBdW indow); 
UpdateMenus; 


FOR i := 1 TO MaxWindows DO 
IF contentWindow = myWindowsli] THEN 
GIN 


currentWindow := i; 
Se tPor t(myW indows [currentW indow 1); 
UpdateMenus; 
END; 
END; 
i := currentWindow; 
IF currentWindow О 0 THEN 
BEGIN 
IF part © Ø THEN 
doScrollersCi, control, part, localpt); 
IF part = 0 THEN 
BEGIN 
IF PtInRectClocalPt, myText([il^^.viewRect) THEN 
BEGIN 


TEClickClocalPt, BitAndCConEvent .modif iers, 
Shif tKey) = Shif tKey, nyTextLi1) 
END; (of ptInRect) 
END; ( of раг{=0 } 
END; (of ашшы 09) 
END; (of proc) 


PROCEDURE doDrag; ((GrabWindow : WindowPtr) 
М (GlobalMouse : point2;) 
VÀ 


i : integer; 
BEGIN 
IF GrebWindow € FrontWindow THEN 
BEGIN 
SelectWindowCGrabWindow); 
IF GrabWindow = ClipBdWindow THEN 
BEGIN 
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currentWindow := 0; 
SetPor t(C1 ipBdWindow); 
UpdateMenus; 
END 
ELSE 
FOR i := 1 TO MaxWindows DO 
IF GrabWindow = myWindows[il THEN 
BEGIN 
currentWindow := i; 
SetPort(CmyW indows[i 12; 
UpdateMenus; 
END; 


END; 
DragWindow(GrabWindow, GlobalMouse, DragÀrea); 
END; 


PROCEDURE doGrow; ((ResizeWindow : WindowPtr;) 
(Globalmouse : point;) 
(ZoomF 19g:Boo1ean);) 
VAR 
newSize : LongInt; 
hsize : integer; 
vsize : integer; 
oldPort : GrafPtr; 
saveRect : rect; 


textlines : integer; 

i : integer; 

windowLines : integer; 

CharPos : integer; 

ControlLine : integer; 

tempLong : LongInt; 
BEGIN 


IF (ResizeWindow © FrontWindow) THEN 
SelectWindowCResizeWindow) 
ELSE 
BEGIN 
IF (ZoomF1g) THEN 
BEGIN 
WITH ResizeWindow^.portRect DO 
BEGI 


tempLong := bottom - top; 
newSize := BitShiftCtempLong, 16); 
newSize := newSize + (right - left); 


newSize := GrowWindow(ResizeWindow, Globalmouse, 
GrowArea); 

IF newSize ‹› 0 THEN 

BEGIN (grow the window) 

hsize := LoWord(newSize); 

vsize := HiWord(newSize); 

IF ResizeWindow = ClipBdWindow THEN 
SizeWindow(ResizeWindow, hsize, vsize, true); 

FOR i := 1 TO MaxWindows DO 


BEGIN 
IF ResizeWindow = myWindowsli] THEN 
BEGIN 
WITH ResizeWindow^.portRect 00 (Pre-Grow) 
BEGIN 


SetRect(VCRect, right - (SBarWidth - 1), top - 1, 
right + 1, bottom - (SBarWidth - 2)); 
SetRectCHCRect, left - 1, bottom - (SBarWidth - 1), 
right - (SBerWidth - 2), bottom + 1); 
SetRectCGrowRect, HCRect.right, HCRect.top, 
VCRect.right, HCRect .bottom); 
END; (of with } 
SizeWindow(ResizeWindow, hsize, vsize, TRUE); 
InvalRect(GrowRect); (Pesky grow icon! !} 
EraseRect(GrowRect); (better if done after sizewind) 
WITH ResizeWindow^.portRect DO (Post Grow) 
BEGIN 
SetRect(VCRect, right - (SBarWidth - 1), top - 1, 
right + 1, bottom - (SBarWidth - 22); 
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SetRect(HCRect, left - 1, bottom - (SBarWidth - 1), 
right - (SBerWidth - 2), bottom + 1); 
SetRect(GrowRect, HCRect.right, HCRect.top, 
VCRect.right, HCRect .bottom); 
SetRect(ViewRect, left + 4, top + 4, right - 
(SBarWidth - 1), bottom - (SBarWidth - 1)); 
END; {of with } 
DestRect := ViewRect; 
InvalRect(GrowRect); (needed for update on shrink) 
HideControlCnyVControls(i 12; 
НІдеСопіго1 СтуНСопіго1$ (11); 
MoveControl(myVControlslil, VCRect.left, VCRect. top); 
MoveControl(myHControlslil, HCRect. left, HCRect. top); 
SizeControlCmyVControlslil, SBerWidth, VCRect.bottom - 
VCRect. top); 
SizeControl(nyHControls(il, HCRect.right - HCRect. left, 
SBarWidth); 
ShowControl(CnyVControls[i 12; 
ShowContro1CnyHControls[i 12; 
ValidrectCHCRect); 
VelidRectCVCRect 2; 
(Updete TextEdit Display) 
nyText[i]^^.ViewRect := ViewRect; 
myTextlil** .DestRect := DestRect; 
currentWindow := i; 
BashText; 


END; (of if ResizeWindow) 
END; (of i =1 to MaxWindows) 
END; (of else grow window stuff) 
END; (of if then newsize) 
END; (of proc) 


END. (of unit) 
: Myr ite.R 


MyMWr ite .RSRC 
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Type DAV1 = STR 
‚0 
9 by David E. Smith ver 1.0 20 NOV 1986 


Type FREF 
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Type BNDL 
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ICN! 
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x ------ Switcher events --------- 


Type SIZE = GNRL 
-1 


, 
РЭР ;,Set bit 14 for resume 
ош ;; 128K preferred 

6904 ;; 128K minimum 
Жозе M DE menus ------------- 
Type MENU 


* the desk acc menu 
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,256 

M4 ,,8pple menu 
About Myhr ite.. 
(- 


* the file menu 


File 
New /N 
(Open... 
Close 
(Save 
(Save as.. 
(Page Setup.. 
(Print. 


(- 
Quit /Q 


* the edit menu 


Clear /D 

(- 

Select A11 /A 
Show Clipboard 


* the search menu 


д 


Search 


* the format menu 
‚ 260 
Format 


* the font menu 


4 


Font 


* the size menu 


* the style menu 


Style 
Plain Text!\12 /P 
Bold«B /B 
Italic«I /I 
Underline«U /U 
Outline«O /0 
Shadow«S /S 
Condense 
Extend 
(- 
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Left /L 
Center /M 
Right /R 


* the mode menu 
, 204 
Mode 
Or 
Xor 
Bic 


* the transfer menu 


Trensfer 
(- 
COther.. 


type DLOG 

, 128 
About MyWrite.. 
100 100 250 400 
Visible NoGoAway 
1 


0 
128 


type DITL 
, 128 


5 
BtnItem Enabled 
112 235 141 284 
к 


StetText Disabled 
14 55 30 256 
MyWrite Text Edit Demo V1.0 


StatText Disabled 
35 138 52 163 


by 


StatText Disabled 
57 91 73 191 
David E. Smith 


PicItem Disabled 
70 9 156 80 
128 


type DLOG 

, 129 
OtherSize 
130 120 207 355 
Visible NoGoAway 
1 


0 
129 
type DITL 

, 129 
3 
BtnItem Enabled 
48 179 74 228 
OK 


StatText Disabled 
5 32 25 205 
Select Font Size: “0 


EditText Disabled 
21 16 44 144 


include DataFrame :MYICON# 
include DataFrame : МҮРІСТ 


David Goldsmith 


MacA pp Ob j ects paz MacApp Project Manager 
| = Apple Computer, Inc. 
A MacApp Text Editor п казса) MacTutor Vol. 3 Мо.2 
The January 1987 issue of MacTutor ° é File Edit Page Tent Font Style Debug р 


contained an article showing how to imple- 

ment a TextEdit based editor, MyWrite, in LS 

Pascal, which allows editing of multiple docu- 

ments at the same time, changing fonts, sizes, 

and styles, and supports the usual Macintosh™ 

features of scrolling, resizing and moving 

windows, and so forth. MyWrite is already a 

pretty sizeable program, but it is still missing 

features, such as: 

1. Saving documents to and reading docu- 
ments from disk. 

2. Support for printing documents. 

3. The ability to undo and redo commands. 

4. Asking the user if s/he wants to save 
changes before closing or quitting. 

5. Displaying informative messages if a 
problem occurs. 


6. Making sure the program doesn’t run out of memory (or 
encounter some other problem) and bomb. 

Although MyWrite has most of the basic features of a 
Macintosh application, there is a big difference between a 
sample application like this and a commercial application. 
Producing a good commercial application requires that you 
attend to many details like those listed above, while also trying 
to conform to the Macintosh user interface and make your 
program competitive in the marketplace. In the pressure to bring 
a program to market, some of these considerations may get short 
shrift, simply because there isn’t time to deal with them. Yet the 
applications which supply all these ingredients are the most 
successful. 

As large as it is, the MyWrite program is simpler than most 
applications because TextEdit does so much. TextEdit provides 
calls to handle mouse clicks, typing, screen update, scrolling, cut 
and paste, highlighting of the current selection, and import and 
export of the clipboard. Most applications, however, do not have 
a convenient ROM package to do all this work for them. The 
result is more work for you. 

On all computers, you must write the part of your applica- 
tion that does a job for the user. On Macintosh, you must also 
provide the intuitive user interface, common functions, and 
friendly operation that Macintosh owners expect. Adding these 
features to a program that’s already large would certainly make 
it much too big to present in the pages of MacTutor — unless we 
do it with MacApp'M. 

What is MacApp? 
MacApp is an object oriented framework for Macintosh 
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|{Copyright 3 1986 by Apple Computer, Inc. 
UNIT UDemoText ; 


| UDemoText.inc! ‚р | 
= UDemoTeut.p ZEE : 
RII Rights 


{This sample application demonstrates the breadth of a | 


Q 


A multiple-window text editor, 
written using MacApp. 


Inspect what object [hex handle, оғ decimal stack leue! 91? gfrontwindow 
ТИІ МООИ $0 1С4Е6 

fNextHandier = $0 1С5 18 

Шіткісе = $01C4E8 fControls = $01C4B4 

fContainer = $000000 fFrameList = $01C4C4  fUiew = $000000 

fContentRect = (0, 09/4352, 93> fUiewedRect = (0, 05/€352, 93) 

OVERA nae = . {a SCP ле m e РЕ m = 1 а 


applications. It's object oriented because it uses Apple's ex- 
tended dialect of Pascal, called Object Pascal, part of the MPW 
development system. It's a framework in that it provides an 
architecture and a collection of tools which make it much easier 
to write a Macintosh application. 

Wherever it can, MacApp handles details which are the 
same for all applications, such as dealing with desk accessories or 
Switcher. Where it can’t do all the work for you, it provides tools 
and a support structure for you to fit your code into which make 
it easy to provide such standard features as Undo, scrolling, and 
printing. MacApp is like a high level Toolbox built on top of the 
Toolbox in the Macintosh ROMs. 

By providing much of the standard behavior of a Macintosh 
application, MacA pp frees you to spend more time making your 
application do a better job for the user. It also enables you to 
refine your user interface and make it better than it would have 
been if you had built it from scratch. The flexibility which lets 
MacApp provide this standard behavior while allowing you to 
alter it comes from Object Pascal. 

All About Objects 

For a good discussion of Object Pascal, see the December 
1986 issue of MacTutor, which has several articles on MacApp. 
For those of you who don't have that issue handy, here is an 
overview of Object Pascal. 

Object Pascal adds a new data type to Pascal, the object. An 
object is very similar to a record, but in addition to conventional 
fields it can also have associated procedures and functions, called 
methods. Justas you would reference a field of a record or object 
by writing record.field, you call a method of an object by writing 
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object. Method(arguments). 

The ability to associate code with the data which that code 
operates on is a powerful tool for making your code more 
modular. However, the real power of object oriented program- 
ming lies in another feature called inheritance. When you 
declare a new object type in Object Pascal, you can give the name 
of an existing object type which becomes the new type's ances- 
tor; the name of the ancestor appears in parentheses (see Figure 
2). The new, descendant type inherits all of the fields and 
methods defined by the ancestral type; that is, any fields and 
methods which the new type defines are in addition to those 
already defined for the ancestral type. 

In addition, the descendant type can override methods 
defined by its ancestor, by providing a new implementation of the 
same method, with the same interface. The override method can 
call the method it is overriding; this allows you to extend the 
function of a method by calling the original version and then 
doingalittle bitextra, instead of duplicating the original code and 
then modifying it. 

Now for the best part: variables actually hold references to 
objects rather than the objects themselves, which are relocatable 
blocks in the Macintosh heap. In fact, a variable of a given object 
type can hold a reference to an object of that type or any of its 
descendant types. When you call a method using a given 
variable, the code which gets executed depends on which particu- 
lar kind of object that variable refers to. If it refers to an object 
of type TRectangle with a method Draw, and you say 
variable.Draw, you'll call the method TRectangle.Draw. But if 
the same variable currently refers to an object whose type is a 
descendant of TRectangle (say TRoundRect), and that descen- 
danttype overrides Draw, then the same statement variable.Draw 
will call the method TRoundRect.Draw instead, which probably 
does something quite different from what TRectangle.Draw 
does. 

How Does MacApp Work? 

Well, objects sound interesting and powerful, but how does 
MacApp use them? The answer is that MacApp defines a set of 
object types which act as generic components of an application. 
These components implement those parts of an application 
which are common to almost all applications, but not the parts 
that make any given application unique. The types MacApp 
defines are: 

1. TApplication, which can handle desk accessories, the clip- 
board, and opening new and old documents. 

2. TDocument, which knows how to read and write disk files, 
handle its windows, and ask if you want to save it when it's 
closed. 

3. TView, which shows the contents of a document. It knows 
how to draw itself on the screen, and process mouse clicks 
and keystrokes. 

4. TFrameand TWindow, which know how to show views, and 
provide scroll bars to look at different parts of those views. 

5. TCommand, which represents a unit of action by the user 
which can be done, undone, or redone. 

What's slightly surprising is that TDocument reads and 
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TRectangle = OBJECT 
bounds: Rect; 
fillPat: Pattern; 
PROCEDURE TRectangle.Draw; 
PROCEDURE TRectangle.Rotate(angle: INTEGER); 
END; 


TRoundRect = OBJECT(TRectangle) 

(Automatically inherits all fields and methods of 
TRectangle, plus: ) 

cornerRadius: INTEGER; 

(This version of method Draw overrides the one 
declared in TRectangle.) 

PROCEDURE TRoundRect.Draw; OVERRIDE; 

END; 


Figure 2. Declaring objects 


writes empty documents, TView displays blank documents, and 
TCommand does nothing when doing, undoing, or redoing. So 
how does a MacApp program do anything useful? By overriding, 
of course. You define object types which are descendants of the 
standard MacApp types, and which supply just that extra knowl- 
edge which makes them do what your application needs to do. 
These types inherit all the standard behavior which you would 
otherwise have to reinvent for every application. That standard 
behavior makes for a very, very long list, and few commercial 
applications implement everything on it. 
The Multi-Window Text Editor 

How would we go about implementing this program in 
MacApp? Well, we don't have to worry about supporting desk 
accessories, Switcher, scrolling, saving and restoring docu- 
ments, Undo, handling errors, displaying meaningful error 
messages, supporting multiple documents open at once, handling 
interactions with the Finder, printing, displaying the Clipboard, 
zoom boxes, resizing or moving windows, or memory manage- 
ment, because MacApp already does all of that for us. 

We are still responsible for implementing that part of our 
application which isn't generic, which in this case means editing 
text using the Toolbox TextEdit package. Fortunately for us, 
though, MacApp comes with a building block which puts a 
MacApp front end on TextEdit by defining a descendant of 
TView called TTEView. Building blocks are add-ons to 
MacApp which provide features that not every application uses. 
Currently, MacApp comes with three building blocks, for print- 
ing, TextEdit, and dialogs. 

Does this mean we've pared the program down to nothing 
atall? Not quite, because the standard TTE View type defined by 
MacApp doesn't support commands for changing the font, size, 
or style of the text being displayed. We'll have to do that 
ourselves. For this article, we'll do it by calling methods of 
TTEView and by calling TextEdit routines to do what we want. 
A cleaner way to do it would be to define a descendant of 
TTEView called, say, TFontsTEView. TFontsTEView would 
define additional methods to do what we need, such as 
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TFontsTEView.ChangeTextSpecs. This would make our work 
reusable in any program which needed a TextEdit view with 
those additional capabilities. | 

Our multi-window text editor, named DemoText, is in fact 
the same as the sample program of the same name which is 
supplied with MacApp, except for some small differences. It 
saves text in documents of type TEXT, with the text in the data 
fork, and the current font information and Page Setup informa- 
tion stored in the resource fork. It doesn't have the Other... font 
size menu command which the MacTutor editor has, but that 
would be fairly easy to add. In fact, it could be added without 
modifying the UDemoText unit at all, by overriding the types 
TTextDocument and TTextApplication in the main program, 
MDemoText.p, and adding that one command. 

If you compare this program to the one done without 
MacApp, you will find that it is significantly shorter and does 
much more. If desired, it could be distributed as a commercial 
product (begging the question of whether there's a market for 
programs which support only one font at a time and no more than 
32K of text). 

Structure of a MacApp Application 

When you use MacApp with MPW (the Macintosh 
Programmer's Workshop) and MPW Pascal, you usually need at 
least five files to specify an application and how to build it: 

1. MYourApp.p, the Pascal source for the main program. 

2. UYourApp.p, the interface file for the Pascal unit which 
defines the main application types. 

3. UYourApp.incl.p, the implementation file for the Pascal unit 
which defines the main application types. Thisisinaseparate 
file so that changes to the implementation do not cause users 
of the unit to be recompiled. 

4. YourApp.r, the input file to the MPW resource compiler, 
Rez. 

5. YourApp.make, a file which specifies the structure of the 
application. MPW's Make tool is very powerful but also very 
complex. MacApp comes with. a set of Make files which 
declare the necessary rules for building a MacApp program; 
all you need do is specify the structure of your program. 

[Note: In terms of hardware, MacTutor recommends you 
buy a 40 meg. hard disk. The MPW and MacApp software runs 
about 8 Meg including source code! Our experience is that a 
typical 20 Meg drive is barely enough for all the non-develop- 
ment type applications and data files. -Ed.] 

It's possible to have applications with more source files by 
making the appropriate declarations in the .make file. 

In MDemoText.p, DemoText.r, and DemoText.make, we 
don't need anything out of the ordinary; these files are similar to 
the templates provided with MacApp. MDemoText.p calls some 
initialization routines and makes the application's one resident 
segment resident in memory (by calling some MacApp utility 
routines). Itthen creates an instance of the application object and 
tells it to run the application. When this call returns, the user has 
selected the Quit command. 

Note that DemoText.r contains only resources specific to 
DemoText, such as its window template and the About De- 
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moText... alert. Some of the other resources are unusual in that 
they don't appear in applications written without MacApp. For 
example, the seg! and mem! resources control the memory 
management features of MacApp (which are too involved to 
discuss here). The cmnuresources are just like MENU resources, 
except that each menu item has an additional component: a 
MacApp command number. А special MPW tool (PostRez) 
strips the command numbers from each menu, creating normal 
MENU resources while also building a table which maps be- 
tween MacApp command numbers and menu and item numbers. 
Notice that there are command numbers defined by both De- 
moText (these are defined in the source) and MacApp (these are 
defined in the MacApp interface files). 
Getting Down to Business 

The parts of the application which actually do the work are 
in UDemoText.p and UDemoTextincl.p, where the 
application's object types are defined. 

As I mentioned above, we won't override TTEView to 
implement DemoText. Instead, we'll define three new descen- 
dants of MacApp objects: TDemoTextApplication, a descen- 
dant of TApplication, TTextDocument, a descendant of TDocu- 
ment, and TTextCommand, a descendant of TCommand. Each 
is responsible for adding features over and above those provided 
by MacApp. 

TDemoTextApplication doesn't have much to do. We just 
provide an initialization method (IDemoTextApplication), and 
override the standard method DoMakeDocument so that the 
application creates the right kind of object to represent our 
documents (the generic TDocument.DoMakeDocument does 
nothing). This one method is called for both new and existing 
documents. 

TTextDocument does the bulk of the work. One object of 
type TTextDocument is created for each document which is 
open. The document object is responsible for making one or 
more views to display the document (method DoMakeViews), 
making one or more windows to display those views in (method 
DoMakeWindows), enabling valid menu commands (method 
DoSetupMenus), and executing those commands when chosen 
(method DoMenuCommand). Note that for both of these latter 
methods, commands not specific to the application are passed on 
via INHERITED so that MacApp can handle them (such as File 
menu commands, Edit menu commands, and so on). 

The document object is also responsible for reading and 
writing files, so DemoText overrides the methods DoRead and 
DoWrite to do so. The method DoNeedDiskSpace calculates the 
disk space needed before the document is saved, and so allows 
MacApp to warn the user beforehand if there is not enough space. 

There are some additional small methods: DolnitialState is 
called when Reverting to a blank document, and FreeData and 
ShowReverted аге both used for all cases of the Revert command. 
Again, we’re only specifying behavior which makes our program 
different from the generic application. TTextDocument also 
defines one new method, InstallTextSpecs, which does the work 
of changing the font, size, style, or justification. 

The last type, TTextCommand, has very little to do. It 
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encapsulates the actions of the commands which change font 
attributes in one object, so that the commands can be easily done, 
undone, and redone. All it has to do is remember the previous 
state of the document's font attributes, then swap them back and 
forth as requested. 

There are some items in the sources which I haven't dis- 
cussed, but that would require more details of MacApp than I 
have room for here. None of them are essential to grasping how 
the program works and how it makes use of MacApp. 

We'venow done everything necessary to make our program 
do what we wanted. АП of the other features we talked about at 
the beginning of this article are taken care of by MacApp. For 
example, because we used TTextCommand to handle our font 
commands, we automatically get Undo and Redo. In addition, 
MacAppknows that this command changes the document, and so 
it knows to ask the user whether or not to save changes. The 
commands for changing how the text is wrapped are not un- 
doable, but could easily be made so by defining another type of 
command object. 

As I mentioned earlier, having the TTEView type available 
made this program simpler, just as having TextEdit in ROM 
made MyWrite easier to write. However, MacApp contains tools 
which make writing any application easier, not just one which 
edits text. MacApp comes with many sample programs which 
demonstrate different kinds of applications, including a 
MacDraw™ -like sample. 

How to Find Out More 

You can find out more about MacApp from: 

1. The December 1986 MacTutor, which has three articles 
on MacApp, including another application. 

2. Kurt Schmucker's book, Object Oriented Programming 
for the Macintosh," Hayden, 1986. This covers MacApp exten- 
sively, and is available in most bookstores. 

3. The MacApp Developer's Association, an independent 
user's group. Their address is: 

MacApp Developer's Association 

PO Box 23 

Everett, WA 98206-0023 

4. The MacApp 1.0 Source Listing and Cross Reference, 
available from the Apple Programmer's and Developer's Asso- 
ciation (APDA). This is not only a good source of information 
on MacApp, buta good place to learn things for programs written 
without MacApp. APDA’s address is: 

Apple Programmer's and Developer's Association 

290 SW 43rd St. 

Renton, WA 98055 

(206) 251-6548 

3. The MacApp Reference Manual, part of the MacApp 
package which is also available from APDA. MacApp currently 
can only be used with the Macintosh Programmer's Workshop 
(MPW) and MPW Pascal, but third party developers are working 
on supporting MacApp in other environments. 

Remember the MacApp team’s motto: “We do the pro- 
gramming, so you don't have to!" 

Macintosh, MacApp, and MacDraw are trademarks of 
Apple Computer, Inc. 
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(File UDenoText.p) 


(Copyright € 1986 by Apple Computer, Inc. А11 Rights Re- 
served. 


UNIT UDemoText; 


(This sample application demonstrates the breadth of alterna- 
tives available when using the MacApp building-block "UTEView" 
for text-editing.) 


INTERFACE 


USES 
($LOAD MacIntf .LOAD) 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
($LOAD UMacApp.LOAD) 
UObject, UList, UMacApp, 
($LOAD) 
UPr inting, 
UTEView; 


CONST 


(Command numbers) 


cWidthFrame = 601; (View-width-determination cmds) 
cWidthView = 692; 
cWidthOnePage = 693; 
cHeightFreme = 604; (View-height-determination cmds) 
CHeightPages = 695; 
cHeightText = 606; 
cHeightConst = 607; 
cJustLef t = 608; (Justification commands) 
cJus tCenter = 609; 
cJustRight = 610; 
(Other constants) 
kSignature = '$904'; (application signature) 
kFileType z 'TEXT'; (file-type code for saved 
disk files -- uses standard text f iles) 
kWindowRsrcID = 1004; (Resource ID of the WIND 


resource used to obtain the windows used by this epp) 


TYPE 


TextSpecs = (Text specif ications} 
RECORD 
theFontNumber: INTEGER; 
theFontSize: INTEGER; 
theStyle: Style; 
theJustification: INTEGER; 
END; 
TextSpecsPtr = ^TextSpecs; 


TextSpecsHd] = ^TextSpecsPtr; 
TDemoTextApplication = OBJECTCTAppl ication) 


PROCEDURE TDemoTextApp! ication. IDemoTextApp] ication; 
(Initialize the Ápoiication) 


FUNCTION TDemoTextAppl ication .DoMakeDocument( 


itsCmdNumber: CmdNumber): TDocument; OVERRIDE; 
(Launches а TTextDocunent} 


($IFC qDebug) 

PROCEDURE TDemoTextAppl ication. IdentifySoftware; OVERRIDE; 
($ENDC) 

END; 

TTextDocument = OBJECTCTDocument ) 


fText: Handle; (The text owned by the 
document} 


221 


f TEView: TTEView; (The view which displays (Command execution phases) 
the text) 


fTextSpecs: TextSpecs; (Specifies properties of PROCEDURE TTextCommand.DoIt; OVERRIDE; 
the text) PROCEDURE TTextCommand.UndoIt; OVERRIDE; 
fSpecsChanged: BOOLEAN; (Specifications have changed since PROCEDURE TTextCommand.RedoIt; OVERRIDE; 
lest time menus were set up) 
fCurrFontMenu: INTEGER; (Currently selected font menu item) END; 

(Initialization and freeing} IMPLEMENTATION 
PROCEDURE TTextDocument . ITextDocument; ($I UDemoText. inc1.p) 
PROCEDURE 'TTextDocument .Free; OVERRIDE; 
PROCEDURE TTextDocument.DoInitialState; OVERRIDE; END. 


PROCEDURE TTextDocument.FreeData; OVERRIDE; 
(File UDenoText. іпсі.р) 


(Filing) 
(Copyright 9 1986 by Apple Computer, Inc. А11 Rights Re- 
PROCEDURE TTextDocument .DoNeedDiskSpace( served.) 
VAR dataForkBytes, rsrcForkBytes: LONGINT); OVERRIDE; 
PROCEDURE TTextDocument .DoRead( CONST 
eRefNum: INTEGER; rsrcExists, forPrinting: BOOLEAN); 
OVERRIDE; (Menu id's} 
PROCEDURE TTextDocument .DoWr i teC mFont = 6; 
eRefNum: INTEGER; makingCopy: BOOLEAN); OVERRIDE; mStyle = 7; 
(Making views and windows) (Command numbers for font-size commands} 
cSizeChange = 0; 
PROCEDURE TTextDocument .DoMakeV iewsCforPrinting: BOOLEAN); cSizeBase = 1100; 
OVERRIDE; cSizeMin = 1109: 
PROCEDURE TTextDocument .DoMakeWindows; OVERRIDE; cSizeMax = 1124; 


(1101-1199 reserved for font sizes 1-99 pts.) 
(Command processing) 


(Command numbers for typestyle attributes) 


FUNCTION TTextDocument .DoMenuCommand( cS ty leChange = 1200; 

aCmdNumber: CmdNumber): TCommand; OVERRIDE; cPlainText z 1201; 
PROCEDURE TTextDocument.DoSetupMenus; OVERRIDE; cBold = 1202; 

cItalic = 1203; 

(Auxiliery routine) cUnder ine = 1204; 

| cOutline = 1205; 

PROCEDURE TTextDocument. Instal1TextSpecs( cShadow = 1206; 

Specs: TextSpecs); cCondense = 1207; 

(Installs the properties implied by values in cExtend = 1208; 


‘specs’ into the TextEdit record) 
(Command numbers to cover other stylistic changes) 


PROCEDURE TTextDocument.ShowReverted; OVERRIDE; cJustChange = 1300; 
(When the user reverts а document, this is called cFontChange = 1301; 
efter reading the old document апа before displaying it. 
Causes the reverted font specs to be installed.) (Constant for staggering windows) 
kStaggerAmount = 16; 
END; 
(Constants for the text specs resource} 
TTextCommand = OBJECTCTCommand) {A Command which changes kTextSpecsRsrcType = 'SPEC'; 
properties of text) kTextSpecsRsrcID = 1; 
fOldTextSpecs: TextSpecs; {Text specifications before (Constants for the print info resource) 
command is done -- used for UNDO} kPrintInfoRsrcType = 'PRNT' ; 
fNewTextSpecs: TextSpecs; (Text specifications after kPrintInfoRsrcID = 1, 
command is done -- used for DO/REDO) 
f TEView: TTEView; (The view to which the (The ‘File is too large’ alert} 
command applies) kFileTooBig - 1000; 
fTextDocument: TTextDocument; (The corresponding text docu- 
nent) VAR 
(Initialization) gFontNum: INTEGER; {Font number - default for new documents) 
gFontSize: INTEGER; (Font Size in points - default for new 
PROCEDURE TTextCommand. I TextCommand( documents} 
itsOndNumber: CmdNumber; gStaggerCount: INTEGER; 
itsTextDocument: TTextDocument; 
itsTEView: TTEView; PROCEDURE OutlineFontSizesCfontNum: INTEGER); FORWARD; 
itsFontNumber: INTEGER; (Makes the right Menu Manager calls so that the 'Font' 
itsFontSize: INTEGER; menu has fontsizes representing ‘natural fonts’ shown in 
itsStyle: Style; ‘outline’, and sizes which can only be achieved by scaling 
itsJustif ication: INTEGER); enother font size shown in normal face) 
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($5 AInit) 
PROCEDURE  TDemoTextApplication.IDemoTextAppl ication; 
VAR err: 05Егг; 
fntNeme: Str255; 
BEGIN 


IApplicetionCkF ileType); 


(Find out what applFont maps to, so that we set gFontNum 
to a real font number. ) 

GetFontNemeCapplFont, fntName); 

GetFNunCfntNeme, gFontNum); 

gFontSize := 10; 


IF NOT gFinderPrinting THEN 
BEGIN 
AddResMenuCGe tMHandleCmFont?), ‘FONT'); 


OutlineFontSizesCgFontNum); 
gStaggerCount := 0; 


(Set style-items to corresponding typeface) 
SetStyleCcBold, [bold1); 
SetStyleCcUnderline, Cunderline]); 
SetStyleCcItalic, [italic]; 
SetStyleCcOutline, [outline1); 
SetStyleCcShadow, [shadow]); 
SetStyleCcCondense, Ісопдегве 1); 
SetStyleCcExtend, [extend]); 
END; 

END; 


($S AOpen} 

FUNCTION TDemoTextApplication.DoMakeDocument( 

itsCmdNumber: CmdNumber): TDocument; OVERRIDE; 
VAR aTextDocument: TTextDocument; 

BEGIN 
NewCaTextDocument ); 
Fai INILCaTextDocument); 
eTextDocument . ITextDocument; 
DoMakeDocument := aTextDocument; 

END; 


($IFC qDebug) 
($8 ADebug) 
PROCEDURE TDemoTextApplication. IdentifySof tware; 
BEGIN 
WriteLnC'DemoText Source date: 23 April 86; Compiled: ', 
COMPDATE, ' @ ', СОМРТІМЕ); 
INHERITED IdentifySof twere; 
END; 
($ENDC) 


($S AOpen} 
PROCEDURE TTextDocument.ITextDocument; 
BEGIN 
fText := NIL; 
IDocument(kFileType, kSignature, kUsesDataFork, 
kUsesRsrcFork, NOT kDataQpen, 
NOT kRsrcOpen); 
fTEView := NIL; 
fText := NewPermHendleC2); 
Fai INILCf Text); 
END; 


($5 AClose) 
PROCEDURE TTextDocument.Free; OVERRIDE; 
BEGIN 
IF fText € NIL THEN 
DisposHendle(CfText); 
INHERITED Free; 
END; 


($S AOpen} 
PROCEDURE TTextDocument.DoInitialState; OVERRIDE; 
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VAR aTEView: 


BEGIN 


WITH fTextSpecs DO 
BEGIN 


theFontNumber := gFontNum; 
theFontSize := gFontSize; 
theStyle := []; 


theJustif ication := teJustLeft; 


END; 
fSpecsChanged := TRUE; 
D; 


($S AOpen) 


PROCEDURE TTextDocument .DoMakeViews( 


forPrinting: BOOLEAN); OVERRIDE; 
TTEView; 

itsExtent: Rect; 

eHandler: TStdPr intHendler; 


BEGIN 
NewCaTEView); 
FailNILCaTEView); 
aTEView.ITEViewC 
NIL, (parent) 
SELF, (its document) 
fText, (its Text) 
PointC0), (location of its top-left-most point) 
cTyping, (its key-command number 
10, (10 pixels of margin on each side) 
8, (8 pixels margin at top) 
1000, (1000 pixels initial view width -- 
will be ed justed to be width of page later} 
100, {100 pixels initial height -- will be 


adjusted to height-of-content later) 

f TextSpecs.theFontNumber, (font family to use) 

f TextSpecs . theFontS ize, (font size to use) 

fTextSpecs.theStyle, (style to use) 

SizePage, (view width determined Cinitially) by 
page-width less desired margins) 

SizeVerieble, {height determined Cinitially) by 
emount of text) 

kUnlinited); 
accepted) 


(no limit to number of characters 


aTEView.fHTE^^.just := fTextSpecs. theJustif ication; 
NewCaHandler ); 

FailNILCaHandler ); 
eHendler.IStdPrintHandlerCaTEView, FALSE); 
aHandler.fMinimalMargins := FALSE; 


($IFC qDebug) 

eTEView.fShowBorders := TRUE; 

alEView.fShowExtraFeedback := TRUE; 
($ENDC) 

fTEView := 
END; 


($S AOpen} 
PROCEDURE TTextDocument .DoMakeWindows; OVERRIDE; 
VAR 


eTEView; 


eWindow: TWindow; 
BEGIN 
eWindow := NewSimpleWindowCkWindowRsrcID, 
NOT kDialogWindow, kWantHScrollBar, 
kWantVScrollBar, fTEView); 
AdeptToScreenCaW indow); 
SimpleStaggerCeWindow, kStaggerAmount, 
kStaggerAmount, gStaggerCount); 
END; 


($8 ASelCommand) 

FUNCTION TTextDocument .DoMenuCommand( 
eCmdNumber: CmdNumber): TCommand; 
VAR sd: SizeDeterminer; 
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aName : 5іг255; 
menu: INTEGER; 
iten: INTEGER; 
newSpecs: TextSpecs; 
eStyleItenm: StyleItem; 


Аы InstallChangedDeterminer(Cvhs: VHSelect); 
IF sd € fTEView.fSizeDeterminer(vhs] THEN 
BEGIN 
f TEView.fSizeDeterminer[vhs] := sd; 
(If we changed the horizontal size determiner, 
we must ask the TTEView to recompute the TE rectangles. } 
F vhs = h THEN 
BEGIN 
IF sd = sizeFreme THEN 
f TEView.FremeChengedS ize 
ELSE IF sd = sizePage THEN 
f TEView.DoPaginat ion; 
END; 
f TEView.AdjustExtent; 
f TEView.fFreme.ForceRedraw; 
END; 
END; 


PROCEDURE LaunchTextCommand( 
aCmdNumber : CmdNumber ); 
VAR aTextCommand: TTextCommand; 
BEGIN 
NewCaTextCommand); 
FailNILCaTextCommand); 
WITH newSpecs DO 
alex tCommand. ITextCommendCaCmdNumber , 
SELF, fTEView, theFontNumber, 
theFontSize, theStyle, theJustification); 
DoMenuCommand := eTextCommand; 


END; 

BEGIN 
DoMenuCommand := gNoChanges; 
newSpecs := fTextSpecs; 


CndToMenuItemCaCmdNumber, menu, item); 
IF CcSizeMin <= aCmdNumber) AND CaCmdNumber <= 
cSizeMax) THEN 
BEGIN 
newSpecs.theFontSize := aCmdNumber - 
cSizeBase ; 
LaunchTextCommand(cS izeChange ); 
END 
ELSE IF menu = mFont THEN 
BEGIN 
GetI tem(GetMHandleCmenu), item, aName); 
GetFNumCaName, newSpecs. theFontNumber ); 
LaunchTextCommand(cF ontChange ); 
END 
ELSE IF CaCmdNumber >= cJustLef t) AND 
CaCmdNumber <= cJustRight) THEN 
BEGIN 
WITH newSpecs DO 
IF aCmdNumber = cJustLeft THEN 


theJustif ication := teJustLeft 
ELSE 
IF aCmdNumber = cJustCenter THEN 

theJustification := teJustCenter 
ELSE 

theJustif ication := teJustRight; 


LeunchTextCommandCcJus tChange 2; 
END 

ELSE IF CaCmdNumber = cPlainText) THEN 
BEGIN 


newSpecs.theStyle := (1; 
LaunchTextCommand(cS ty leChenge?; 
END 

ELSE IF CaCmdNumber > cPlainText) AND 
CaCmdNumber <= cExtend) THEN 
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BEGIN 

CASE aCmdNumber OF 
cBold: eStyleItem := bold; 
cItalic: eStyleIten := italic; 
cUnder line: eStyleIten := underline; 
cOutline: aStyleItem := outline; 
cShadow : eStyleItem := shadow; 


cCondense:aStyleItem := condense; 
cExtend: aStylelItem := extend; 
END; (cese) 
WITH newSpecs DO 
IF aStyleItem IN theStyle THEN 
theStyle := theStyle - [aStyleI tem] 
ELSE 
theStyle := theStyle + [aStyleItem); 
oe tCommand(cS tyleChange ); 
ND 


ELSE 
IF CaCmdNumber <= cWidthOnePage) AND 
CaCmdNumber >= cWidthFrame) THEN 
BEGIN 
IF aCmdNumber = cWidthFrame THEN 
Sd := sizeFreme 
ELSE 


IF aCmdNumber = cWidthOnePage THEN 
Sd := sizePage 
ELSE 


sd := sizeF ixed; 
(NB: The following is not undoable in the current 
version) 
Instal 1ChangedDeterminer Ch); 
END 
ELSE 
IF CaCmdNumber >= cHeightFrame) AND 
CaCmdNumber <= cHeightConst) THEN 
BEGIN 
IF aCmdNumber = cHeightFreme THEN 
Sd := sizeFrame 
ELSE 


IF aCmdNumber = cHeightPages THEN 
sd := sizeFillPages 
ELSE 


IF aCmdNumber = cHeightText THEN 
sd := sizeVariable 
ELSE 


IF aCmdNumber = cHeightConst THEN 
Sd := sizeF ixed; 


(NB: The following is not undoable in the current 
version} 

Instal }ChangedDeterminer(v); 

END 


ELSE 
DoMenuCommand := 
INHERITED DoMenuCommand( aCmdNumber ); 


END; 


($5 


MiriteFile) 


PROCEDURE TTextDocument .DoNeedD iskSpace( 


VAR deteForkBytes, rsrcForkBytes: LONGINT); 


BEGIN 
dateForkBytes := deteForkBytes + 
GetHandleSizeCfText); 
rsrcForkBytes := rsrcForkBytes + SIZEOF(TextSpecs) + 


END 
($5 


kRsrcTypeOverhead + kRsrcOverheed + 
kPrintInfoSize * kRsrcTypeOverheed * kRsrcÜver- 
“INHERITED DoNeedDiskSpace(dataForkBytes, 
rsrcForkBytes); 


% 


Ф 


AReadF 11е) 


PROCEDURE TTextDocument .DoReadCaRefNum: INTEGER; 


rsrcExists, forPrinting: BOOLEAN); 
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VAR numChers: LONGINT; 
hTextSpecs: TextSpecsHd1; 
hPrintInfo: Handle; 


BEGIN 
(Reed the text) 
FailOSErrCGetEOFCaRefNum, numChars)); 


(The file may have been created by someone else--make 
sure we don't read more than we can handle) 
IF numChars > kUnlimited THEN 
BEGIN 
gApplication.ShowError(9, msgAlert + kFileTooBig); 
numChars := kUnlimited; 


END; 
SetHandleSizeCfText, numChars); 
FailMemError; 
Fai l0SErr(FSReadCaRefNum, numChars, fText*)); 


(Read the text specs resource) 
hTextSpecs := 
TextSpecsHd1(GetResource(kTextSpecsRsrcType, 
kTextSpecsRsrcID)); 
IF hTextSpecs <> NIL THEN 
fTextSpecs := hTextSpecs^^ 
ELSE 
WITH fTextSpecs DO 
BEGIN 


theFontNumber := gFontNum; 
theFontSize := gFontSize; 
theStyle := [], 
theJustification := teJustLeft; 
END; 

fSpecsChanged := TRUE; 


(Read the print info resource) 
hPrintInfo := GetResourceCkPr int Inf oRsrcType, 
kPrintInfoRsrcID); 

IF hPrintInfo «» NIL THEN (no 


saved 
BEGIN 
IF fPrintInfo = NIL THEN 
BEGIN 
fPrintInfo := NewPermHandleCkPr intInfoSize); 
FailNILCfPrintInfo); 


int info resources was 


END 
BlockMoveChPr int Info^, fPrintInfo^, kPrintInfoSize); 
END; 
END; 


($$ ARes) 
PROCEDURE TTextDocument .DoSetupMenus; 
VAR sd: SizeDeterniner; 
just: INTEGER; 
item: INTEGER; 
fnt: INTEGER; 
с: INTEGER; 
eNeme : Str255; 
eMenuHendle: MenuHandle; 
eStyle: Style; 


IN 
INHERITED DoSetupMenus; 


eMenuHendle := GetMHendle(mFont); 
FOR item := 1 TO CountMI temsCaMenuHandle) DO 
BEGIN 
(There cen be more than 31 menu entries with 
scrolling menus, but trying to enable an item with number > 31 
is bad news. If the menu itself is enabled (which it will be 
in MacApp if any of the first 31 items is enabled), then the 
extras will always be enabled.) 
IF item <= 31 THEN 
EnableI temCaMenuHandle, item); 
IF fSpecsChanged THEN 
BEGIN 
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GetItemCaMenuHandle, item, aName); 
GetFNumCaName, fnt); 

IF fnt = fTextSpecs.theFontNumber THEN 
қ fCurrFontMenu := item; 

D; 


END; 
CheckItemCeMenuHandle, fCurrFontMenu, TRUE); 


FOR c := cSizeMin TO cSizeMax DO 
EnableCheck(c, TRUE, (c - cSizeBase) = 
fTextSpecs. theFontSize); 


eStyle := fTextSpecs. theStyle; 
EnebleCheckCcPlainText, TRUE, aStyle = []); 
EnableCheck(cBold, TRUE, bold IN aStyle); 
EnableCheck(cItalic, TRUE, italic IN aStyle); 
EnableCheck(cUnderline, TRUE, underline IN aStyle); 
EnableCheck(cOutline, TRUE, outline IN aStyle); 
EnableCheck(cExtend, TRUE, extend IN aStyle); 
EnableCheck(cCondense, TRUE, condense IN aStyle); 
EnableCheck(cShadow, TRUE, shadow IN aStyle); 


sd := fTEView.fSizeDeterminer [h]; 
EnableCheck(cWidthFrame, TRUE, (sd = sizeFrame)); 
EnableCheck(cWidthOnePage, TRUE, (sd = sizePage)); 
EnebleCheckCcWidthView, TRUE, (sd = sizeFixed)); 


sd := fTEView.fSizeDeterminer(v]; 

EnableCheck(cHeightFrame, TRUE, (sd = sizeFrame)); 

EnableCheck(cHeightPages, TRUE, (sd = 
sizeFillPages)); 

EnableCheck(cHeightText, TRUE, (sd = sizeVariable)); 

EnebleCheckCcHeightConst, TRUE, (sd = sizeFixed)); 


just := fTextSpecs. theJustif ication; 
EnableCheck(cJustLeft, TRUE, (just = teJustLef t2); 
EnebleCheckCcJustCenter, TRUE, (just = teJustCenter)); 
EnebleCheckCcJustRight, TRUE, Cjust = teJustRight)); 


IF fSpecsChanged THEN 
Out] ineFontSizes(fTextSpecs. theFontNumber ); 
fSpecsChanged := FALSE; 
D: 


Ф 


($S AWriteFile) 
PROCEDURE TTextDocument .DoWr i teCeRefNum: INTEGER; maekingCopy: 


ВОО! ЕАМ), 

VAR numChers: LONGINT; 
hTextSpecs: TextSpecsHd1! ; 
tempHandle: Handle; 

BEGIN 


(Write out the text) 
numChers := GetHandleSize(fText); 
Fail0SErrCFSWriteCaRefNum, numChars, fText*)); 


(Write the text specification resource, after converting 
it to a handle} 
hTextSpecs := 
TextSpecsHdlCNewHandleCSIZEOF ( TextSpecs))); 
FailNILChTextSpecs); 
hTextSpecs^^ := fTextSpecs; 
AddResourceCHandleChTextSpecs), 
kTextSpecsRsrcType, kTextSpecsRsrcID, ''2; 
FailResError; 


(Write the print info resource. Note we can't use MacApp 
for this because MacApp will write the print info into the 
data fork. Note also--we must copy the print info resource to 
another handle because the Resource Manager will dispose of 
the resource handles when а resource fork is closed} 

tempHandle := fPrintInfo; 

FailOSErrCHendTohand( tempHandle)); 

AddResource(tempHandle, kPrintInfoRsrcType, 
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kPrintInfoRsrcID, ''2; 
FailResError; 
END; 


($5 AClose) 
PROCEDURE TTextDocument.FreeData; OVERRIDE; 
BEGIN 

SetHandleSizeCfText, 0); 


(45 ARes) 


PROCEDURE TTextDocument . InstallTextSpecsC 
specs: TextSpecs); 


VAR 
savedPort: GrafPtr; 
tempPor t: GrafPort; 
newInfo: FontInfo; 
BEGIN 


(Meke sure the font info record is correct. We may need 
to do this when the window isn't around, so roll our own 
GrefPort.) 

GetPort(savedPort); 

OpenPortCétenpPort); 

WITH specs DO 

BEGIN 
TextFontCtheFontNumber ); 
TextSizeCtheFontS ize); 
TextFaceCtheStyle?; 

END; 

GetFontInfoCnewInfo); 

ClosePor t(@tempPort); 

SetPor t(savedPor t ); 


fTextSpecs := specs; 
fSpecsChanged := TRUE; 


WITH fTEView, specs DO 
BEGIN 


fFont := theFontNumber ; 
fSize := theFontSize; 
fFontInfo := newInfo; 
WITH fHTE^^ DO 


BEGIN 
WITH newInfo DO 
BEGIN 
fontAscent := ascent; 
lineHeight := ascent*descent*leading; 
END; 


txSize := theFontSize; 
txFont := theFontNumber; 
txFace := theStyle; 
just := theJustification; 
fFreme.fScrollUnit.v := lineHeight; 
END; 
END; 
fTEView.RecalcText; 
f TEView.DoPaginat ion; 
END; 


($5 AReedFile) 

PROCEDURE TTextDocument . ShowRever ted; 

BEGIN 
Instal lTextSpecs(f TextSpecs?; 
TESetSelect(@, 0, fTEView.fHTE); 
INHERITED ShowReverted; 

END; 


($$ ARes) 
PROCEDURE OutlineFontSizesCfontNum: INTEGER); 
VAR с: CndNumber ; 


BEGIN 
FOR c := cSizeMin TO cSizeMax DO 
BEGIN 
IF RealFont(fontNum, c - cSizeBase) THEN 
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D; 
($8 ADoCommend) 
Im TTextCommand.UndoIt; OVERRIDE; 
END; 
($5 ADoCommand) 
PROCEDURE TTextCommand.RedoIt; OVERRIDE; 
BEGIN 
END; 


(File MDenoText.p) 


SetStyleCc, [outline1) 
LSE 


SetStyleCc, (12; 
END; 


END; 


($5 ASelCommand) 
PROCEDURE TTextCommand. ITextCommand( 


itsCmdNumber: CmdNumber; 
itsTextDocument: TTextDocument; 
itsTEView: TTEView; 
itsFontNumber: INTEGER; 
itsFontSize: INTEGER; 

itsStyle: Style; 

itsJustif ication: INTEGER); 


BEGIN 


ICommandC i tsCmdNumber ); 

fTEView := itsTEView; 

fTextDocument := itsTextDocument; 

WITH fOldTextSpecs, itsTEView.fHTE^^ DO 
BEGIN 
theFontNumber := txFont; 
theFontSize := txSize; 
theStyle := txFace; 
theJustif ication := just; 
END; 


WITH fNewTextSpecs DO 
BEGIN 
theFontNumber := itsFontNumber ; 
theFontSize := itsFontSize; 
theStyle := itsStyle; 
theJustif ication := itsJustif ication; 
END; 


END; 


($5 ADoCommand) 
iam TTextCommand.DoIt; OVERRIDE; 


f TextDocument . Instal1TextSpecs( fNewTextSpecs); 


f TextDocument . Instal 1 TextSpecs(f01dTextSpecs); 


f Tex tDocument . InstallTextSpecsCfNewTextSpecs?; 


(Copyright 9 1986 by Apple Computer, Inc. А11 Rights Re- 
served.) 


PROGRAM DemoText; 


8 
($L0AD MacIntf .LOAD) 
MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, 
($LOAD UMacApp.LOAD) 
UObject, UList, UMacApp, 
($LOAD) 
UPr inting, 
UTEV iew, 
UDemoText ; 


VAR 


gDemoTextApp! ication: TDemoTextApp lication; 
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($S ARes) ); 
PROCEDURE InAResSegnment ; /* (2) */ 
BEGIN (10, 80, 110, 270), 
END; SteticText ( 
disebled, 
($S Main) "This sample program demonstrates" 
BEGIN " how to use various features of " 
InitToolbox(8); (Initialize the ToolBox, 8 calls to "the “TEView” building block of M" 
MoreMasters) "acApp. " 
InitPrinting; (Initialize the Printing unit) ); 
SetRes identSegment (Ge tSegNumber C /* [3] */ 
@InAResSegment), TRUE); (10, 20, 42, 52), 
NewCgDemoTextApplication); Icon ( 
gDemoTextApplication. IDemoTextApp] ication; disabled, 
gDemoTextApplication.Run; 
END. ) 
/* DemoText.r - Resource compiler input file */ ); 


/* Copyright € 1986 Apple Computer, Inc. */ 


resource 'ALRT' (201, purgeable) ( 


tifdef Debugging (00, 100, 250, 412), 


include MacAppRF iles"Debug.rsrc"; 201, 
endif 
include MacAppRF iles"MacApp.rsrc"; OK, visible, silent; 
include MacAppRF iles"Printing.rsrc"; OK, visible, silent; 
include "DemoText" ‘CODE’; OK, visible, silent; 
OK, visible, silent 
resource 'WIND' (1004, purgeable) ( ) 
(50, 40, 250, 450), ); 
zoomDocProc, 
invisible, /* Used when the user attempts to read а file larger than we 
goAway, can handle */ 
0x0, 
"Со" resource 'DITL' (1000, purgeable) ( 
); (  /* array DiTLerray: 3 elements */ 
i ; /* (1) */ 
resource 'SIZE' (-1) { (82, 198, 100, 272), 
saveScreen, Button ( 
acceptSuspendResumeE vents, enebled, 
“ifdef Debugging "OK" 
(307-32) * 1024, ); 
(241-32) * 1024 /* (2) */ 
telse (10, 70, 77, 272), 
(212-32) * 1024, StaticText ( 
(152-32) * 1024 disebled, 
“елді! "DemoText can’t read the entire file because it 
) is too long." 
/* Printing to the LaserWriter is the time when the most /® (3) */ 
temporary memory is in use. We need the segments in use at (10, 20, 42, 52), 
that time, plus 40K for the driver's needs. */ Icon ( 
disebled, 
resource 'seg!' (256, purgeable) ( Ü 
"GSelComnmand" ; ) i 
"бРг1п{"; ); 
"PrintNonRes" ; 
"ARes" resource 'ALRT' (1000, purgeable) ( 
(100, 110, 210, 402), 
); 1000, 
(  /* array: 4 elements */ 
resource 'mem!' (256, purgeable) ( /* (1) */ 
40 * 1024, /* Add to temporary reserve */ OK, visible, silent; 
0, /* Add to permanent reserve */ /* (2) */ 
0 /* Add to stack space */ OK, visible, silent; 
); /* (3] */ 
OK, visible, silent; 
resource 'DITL' (201, purgeeble) ( /* (4) */ 
/* array DITLarrey: 3 elements */ OK, visible, silent 
/* (1) */ ) 
(130, 182, 150, 262), ); 
Button ( 
о resource 'cmu' CD ( 


1, 
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); 


textMenuProc, 

OxTFFFFFFD, 

enabled, 

apple, 
( /* array: 2 elements */ 

/* (1) */ 

"About DemoText.", noIcon, noKey, noMark, plain, 1; 

/* [2] */ 

"-", nolcon, noKey, noMark, plain, nocommand 


) 


resource 'cmnu' (2) ( 


); 


2, 

textMenuProc, 

Ox7FFFEEFB, 

enabled, 

"File", 
( /% array: 14 elements */ 

/* [1] */ 

"New", поїсоп, "М", noMerk, plain, 10; 

/* (2) */ 

"Open.", noIcon, noKey, noMerk, plain, 20; 

/* 13) */ 

"=" nolcon, noKey, noMark, plain, nocommend; 

/* [4] */ 

"Close", noIcon, noKey, noMark, plain, 31; 

/* [5] */ 

"Save", noIcon, noKey, noMark, plain, 30; 

/* [61 */ 

"Seve As..", noIcon, noKey, noMark, plain, 32; 

/* [Т] */ 

"Seve а Copy In.", noIcon, noKey, noMark, plain, 33; 

/* [8] */ 

"Revert", noIcon, noKey, noMark, plain, 34; 

/* [9] */ 

"-", nolIcon, noKey, noMerk, plain, nocommand; 

/* (10] */ 

"Page Setup.", noIcon, noKey, noMark, plain, 176; 

/* [11] */ 

"Print One", noIcon, noKey, noMark, plain, 177; 

/* (121 */ 

"Print.", noIcon, noKey, noMerk, plein, 178; 

/* [13] */ 

"=", noIcon, noKey, noMerk, plain, nocommand; 

/* [14] */ 

"Quit", noIcon, "Q", noMark, plain, 36 


) 


resource ‘cmnu' (3) ( 


3, 

textMenuProc, 

OxTFFFFEBD, 

enabled, 

"Edit", 
( /* array: 10 elements */ 

/* [1) */ 

"Undo", noIcon, "2", noMark, plain, 101; 

/* [2] */ 

"=", nolIcon, noKey, noMark, plain, nocommand; 

/* (3) */ 

"Cut", noIcon, "X", noMark, plain, 193; 

/* [4] */ 

"Copy", noIcon, "C", noMark, plain, 104; 

/* (5) */ 

"Peste", noIcon, "V", noMark, plain, 105; 

/* [6] */ 

"Clear", noIcon, noKey, noMark, plain, 106; 

/* [Т] */ 

"-", nolIcon, noKey, noMerk, plain, nocommand; 

/* [8] */ 

"Select A11", noIcon, "A", noMark, plain, 110; 

/* (9] */ 
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, noIcon, noKey, noMerk, plain, nocommand; 
/* [10] */ 
"Show Clipboard", noIcon, noKey, noMark, plain, 35 


); 
resource 'cmu' (4) ( 


textMenuProc, 
Ox7FFFFF37, 
enabled, 


/* аггау: 6 elements */ 
/* [1] */ 
"Show Page Breaks", noIcon, noKey, noMark, plain, 


/* [21 */ 
"Show Page Numbers", noIcon, noKey, noMerk, plain, 


201; 


211; 

/* [3] */ 

"Number Pages Top to Bottom", noIcon, noKey, noMark, 
plein, 206; 

/* (4) */ 

"=", nolcon, noKey, noMark, plain, nocommand; 

/* [5] */ 

"Drew Frame when Printing", noIcon, noKey, noMark, 
plein, 202; 

/* (6) */ 

"Print Page Numbers when Printing", noIcon, noKey, 
аг" plein, 207 


); 
resource 'стпи' (5) ( 


{ех{МепиРгос, 
@хТЕЕЕЕЕЕТ, 


/* (1) */ 

"View as wide as frame", noIcon, noKey, поМагк, 
plain, 601; 

/* 12) */ 
ти "View width frozen", nolcon, noKey, noMerk, plain, 

7 

/* [3] */ 

"View as wide as one page", noIcon, noKey, noMark, 
plein, 603; 

/* [4] */ 

"=", nolIcon, noKey, noMark, plain, nocommand; 

/* [5] */ 

"View as high as the frame", nolcon, noKey, noMerk, 
plein, 604; 

/* [6] */ 

"View height an exact number of p" 

"eges", noIcon, noKey, noMark, plain, 605; 

/* (7) */ 

"View es high as its content", поїсол, noKey, 
noMark, plain, 606; 

/* 


(8) */ 
"View height frozen", noIcon, noKey, noMark, plain, 
607; 
| /% (9) */ 
"=", nolcon, noKey, noMark, plain, nocommand; 
/* [10] */ 
"Left justified", noIcon, noKey, noMerk, plain, 608; 
/* [11] */ 
"Center justified", noIcon, noKey, noMerk, plain, 
609: 
/* [12] */ 
"Right justified", noIcon, noKey, поМәгк, plein, 610 
); 
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resource 'MENU' (6) ( 


textMenuProc, 
al lEnabled, 


) 
); 


resource 'cmnu' (7) ( 


textMenuProc, 
Ox 7FFFFFBF , 
enabled, 
"Style", 
( /* array: 13 elements */ 
/* (1) */ 
" 9 Point", noIcon, noKey, noMark, plain, 1109; 
/* (2) */ 
"10 Point", noIcon, noKey, noMark, plain, 1110; 
/* (3) */ 
"12 Point", noIcon, noKey, noMark, plain, 1112; 
/* [4] */ 
"14 Point", noIcon, noKey, noMark, plain, 1114; 
/* (5) */ 
"18 Point", noIcon, noKey, noMark, plain, 1118; 
/* (6) */ 
"24 Point", noIcon, noKey, noMark, plain, 1124; 
/* (7) */ 
"=", noIcon, noKey, noMark, plain, nocommand; 
/* (8] */ 
"Plain Text", noIcon, "P", noMark, plain, 1201; 
/* (9) */ 
"Bold", noIcon, "B", noMerk, plein, 1202; 
/* [10] */ 
"Italic", nolIcon, "I", noMark, plain, 1203; 
/* (11] */ 
"Underline", noIcon, "U", noMark, plein, 1204; 
/* (12) */ 
"Outline", noIcon, "0", noMerk, plain, 1205; 
/* (13) */ 
"Shadow", noIcon, "S", noMerk, plein, 1206 
); 


resource 'cmnu' (128) ( 


textMenuProc, 
ellEnebled, 
enabled, 
"Buzzwords", 
( /* array: 6 elements */ 
"Typing", noIcon, noKey, noMark, plain, 120; 
"Size Change", nolcon, noKey, noMark, plain, 1100; 
"Style Change", noIcon, noKey, поМагк, plain, 1200; 
“Justification Change", noIcon, noKey, noMark, 
plain, 1300; 
"Font Change”, noIcon, noKey, noMark, plain, 1301; 
"Page Setup Change", nolIcon, noKey, noMark, plain, 
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) 
); 
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resource 'MBAR' (128) ( 
(1; 2; 3; 4; 5; 6; 7) 
; 


* DemoText.make - describes structure of program to МасАрр 

* Copyright 9 1986 Apple Computer, Inc. АТП Rights Reserved. 
AppName = DemoText 

Creator = "5504" 


я List the system libraries that your application needs to 
я link with. If you аге not sure, list everything and the 
8# linker will tell you which ones it did not need 


NeededSysLibs = à 
" (Libreries)RunTime.o" à 
"(Libreries)Interface.o" à 
" (PLibraries)PesL ib .o" 


н List here the MacApp building blocks that your арр11са- 
tion uses 


BuildingBlockIntf = д 
" (SrcMacApp)UPrinting.p" à 
" (SrcMacApp)UTEV iew . p" 


a List the sene MacApp building blocks as object files (for 
linking) 
BuildingBlock0bjs = д 


" (0bjMecApp)UPrinting.p.o" à 
" (0b jMacApp)UTEV iew .р.о" 


8 List any additional pascal interface files which your 
application uses 


Other Interfaces = 

8 By default MacApp.make links the above libraries, 811 of 
* MacApp, and the files UAppName.p.o and MAppName.p.o 

® List any additional files that your program links with: 
OtherLinkFiles = 


8 — Specify any -sn (segment alias) linker options that you 
want included. 


OtherSegMappings = 

8 List the dependencies of the additional files 

н (апа special build rules, if any) 

% List Rez files other than AppNeme.r that need to Rez'ed 
with the epplication 

OtherRezFiles = 

* List resource files that the Rez file includes 


OtherRsrcF iles = à as 
" (RezMacApp)Pr int ing.rsrc" Se. 3 


GE. 
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Pascal Procedures 
Understanding Graf3D 


Almost everybody has heard of GRAF3D for the Mac, but 
aside from Boxes, Sinegrid, and BoxSphere, there is little evi- 
dence of its use. This is probably because the only documentation 
in general distribution is in the form of the source code for the 
above programs, and in the interface files for the various compil- 
ers. As it turns out, there is a pre-release tech note from Apple 
which does a good job of explaining a lot of how GRAF3D 
works, if you're a registered developer. 

In this article, I will present a brief explanation of some 
basic concepts of 3D math, an overview of how the Mac's Graf3D 
routines deal with those concepts, the data types and routines that 
make up Graf3d, and finally, a sample program that tries to 
clarify the difference between two of what I consider Graf3D's 
more confusing concepts. 

The program included with this article was developed in 
LightSpeed Pascal and then converted to Borland Turbo Pascal, 
So the article also presents a small comparison between the two 
language implementations. 

3D Concepts 

There are several basic concepts of 3D graphics with which 
you will need to be familiar if you are going to be able to use 
Graf3D to its fullest extent. Among these are the coordinate 
system conventions and the various transformations and their 
meaning. 

The Coordinate System 

Three dimensional graphics are generally dealt with using 
a right-handed cartesian coordinate system (see fig. 1) 

The three axes are labeled X, Y, and Z. Thus, each point in 
three dimensional space can be represented by three values. 
When displaying such a three-dimensional space on a two- 
dimensional surface (a Mac's screen, for instance) some basic 
trigonometric calculations are used to map the points into their 
proper positions. The basics of this were discovered by artists 
during the renaissance. 

Transformations 

There are three transformations we will want to use to 
manipulate three-dimensional images. These are rotation, scal- 
ing, and transformation. 

Rotation can be about any of the three axes. Rotation about 
the X axis is called Pitch. Rotation about the Y axis is called Yaw, 
and rotation about the Z axis is called Roll. (These terms come 
primarily from the aviation world.) Rotations are performed 
relative to the coordinate system's origin. Thus, if you wish to 
rotate an object around its own center, you need to move the 
object's center to the origin (mathematically, at least), rotate it, 
and then return to the prior coordinates. 

Scaling is a very useful transformation. It serves to move a 
point toward or away from the origin. This can serve to change 


230 


5-0 Application 


Scott Berfield 
Mindscape, Inc. 
MacTutor Vol. 3 No. 3 


Fig. 1 3-D Coordinate System 


the apparent size of the object on screen. 

Translation moves a three-dimensional point some distance 
in any direction. 

Graf3D Concepts 

The coordinate space of Graf3D is anatural extension of the 
Quickdraw system into a third dimension. Just as Quickdraw can 
address a plane ranging from -32767 to +32767 in both dimen- 
sions, Graf3D addresses a cube ranging from -32767 to +32767 


+32767 


+32767 
X 


Graf3D uses a right-handed 
coordinate system. Note the 
orientation of the Y axis. 


+32767 


Fig. 2 GrafPort Orlentation 
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along all three (X, Y, and Z) axes. (See fig. 2) 

Note that the Y axis increases downward as opposed to the 
normal Mac coordinate system. 

This leads to the basic data structure of Graf3D, the 
Point3D. The definition of a Point3D is: 


Туре Poin3D = Record 
X : Fixed; 
Y : Fixed; 
Z : Fixed; 
end; 


The use of fixed-point numbers may be unfamiliar to many. 
A fixed-point number is a special way of handling numbers from 
-32767 to +32767 with up to five decimals of precision. The 
numbers are represented using longints. Thus the massive num- 
bers of floating point calculations needed for 3D math can be 
sped up tremendously by using only integers. 

If you need to translate from floating point to fixed numbers, 
you can either multiply the value by 65536, or you can use the 
routine FixRatio from the fixed-point math package to dived 
your value by one: 

fixedvalue:=FixRatio(FPvalue,1)); 
The Transformation Matrix 

In 3D graphics, it is common to combine all the math 
involved in rotating, scaling, and translating a point into one 4x4 
matrix. The mathematical reasons behind this are beyond the 
scope of this article, but they are well documented in the books 
listed at the end of the article. 

Graf3D defines a data type XfMatrix to handle these 
manipulations. This matrix can be post-multiplied by a Point3D 
to yield a new point which is the product of the three transforma- 
tions. The XfMatrix is defined as: 

Туре XfMatrix = Аггау[0..3,0..3] of Fixed; 


The array holds the results of all operations performed with 
a specific Graf3D coordinate system and can be applied to any 
and all points in the system. 

The Port3D 

Just as Quickdraw defines a grafport, Graf3D defines the 
Port3D. A Port3D is a complete graphics environment. You can 
have many separate Port3D's open at one time, each with its own 
coordinate system, pen location, transformation matrix, and 
screen mapping. (See fig. 3 on the next page.) 

À Port3D is defined as a dynamic data structure as follows: 


Type Port3DPtr = ^Port3D 
Port3D = Record 

GrPort: GrafPtr; 
viewrect: Rect; 
xLeft, xRight: Fixed; 
yTop, yBottom: Fixed; 
pen, penPrime: Point3D; 
eye: Point3D; 
hSize, vSize: Fixed; 
hCenter, vCenter: Fixed; 
xCotan, yCotan: X Fixed; 
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ident: 
xForm: 
end; 


Boolean; 
XfMatrix; 


All operations on Port3D's refer to the port through 
Port3DPu's. 

According to Apple, although all the fields of a Port3D can 
be accessed normally, you shouldn't store any new values into 
them directly. Graf3D has routines for altering all the fields 
which will produce no harmful side effects. 

The fields of the Port3D are as follows: 

GrPort 

This is the corresponding grafport which is used for drawing 
when using the Port3D. The default is the current port. 
Viewrect 

The viewrect field defines a subset of the grafport's portRect 
for use by the Port3D. АП drawing will happen in this 
rectangle. The bounds of this rectangle are initially set to 
GrPort^.portBits.bounds. 

XLeft, XRight, YTop, YBottom 

These fields define the coordinate system, in fixed-point 
numbers, of the current Port3D. I call the volume of space 
defined by these numbers (using the LookAt procedure) the 
"Image Space." These numbers do not have to match the the 
viewport values, and in fact will be scaled to fit the viewrect. 
Pen 

The pen location in 3D space. 

PenPrime 

PenPrime is the location of the pen in 3D space after multiply- 
ing by the transformation matrix. 

Eye 

This is the location of the viewer's eye in threespace. It is 
where you would be standing if you were a part of the 
coordinate system. 

HSize, VSize 

HSize is 1/2 the width of the viewrect. VSize is -1/2 the height 
of the viewrect. Both values are stored as fixed-point numbers. 
HCenter, VCenter 

The centers, in fixed-point, of the X and Y axes of the 
viewrect. 

XCotan, YCotan 

Viewing cotangents used to transform 3D coordinates into 2D 
screen coordinates. 

Ident 

A flag which indicates whether the matrix is currently at 
identity (its original state). 

XForm 

The transformation matrix from the current Port3D. 

The Pen 

The pen and penPrime fields of a Port3D deal with the 3D 
graphics pen. Each port has only one graphics pen, which is 
used for calculating screen coordinates. The 3D pen has only 
one characteristic: location. The Port3D pen and the grafPort 
pen are two different items, one with a 3D location, and one 
with a screen location. The grafPort pen does all the drawing 
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Viewing Pyramid 


Projection plane 


3D Space 
— 


(Set with ViewPort procedure) 


Image Space 
(Set with LookAt Procedure) 


The projection plane is displayed on-screen in the re3ctangle given in the ViewPort 
procedure. The portion of 3D space mapped into that rectangle is determined by the 
LookAt procedure. The coordinates supplied to LookAt will be used to scale all three axes 


to fit in the ViewPort. 


for the 3D pen. The grafPort pen will not be changed by any 

Port3D operations. 

Graf3D Routines 

Initiallzation and Control 

Procedure InitGraf3D(globalPtr : Ptr); 
This is Graf3D's functional equivalent to quickdraw's 
InitGraf. It initializes the current Port3Dptr to globalptr. In 
Pascal, you should always pass @thePort3D. You will 
normally want to call this procedure immediately upon 
initializing quickdraw. 

initGgraf(@thePort); 
initGraf3D(@thePort3D); 

Procedure OpenPort3D(port:Port3DPtr); 
Initializes all fields of a port3D to the defaults and sets that 
port as the current one. 

Procedure SetPort3D(Port: Port3DPtr); 
Makes port the current Port3D and calls SetPort for that 
Port3D's associated grafPort. 

Procedure GetPort3D(Port: Port3DPtr); 
Returns a pointer to the current Port3D. GetPort3D and 
SetPort3D can be used to change between multiple 
Port3D's. 

Controlling the Pen 

Procedure MoveTo2D(x.y fixed); 
Moves the pen to the coordinates x,y while remaining in 
the same z plane. 


232 


Fig. 3 


Procedure MoveTo3D(x.y,z fixed); 
Moves the pen to the coordinates x,y,z. 

Procedure Move2D(dx,dy-fixed); 
Moves the pen to x4dx, y--dy while remaining in the same 
z plane. 

Procedure Move3D(dx,dy,dz fixed); 
Moves the pen to x+dx, y+dy, z+dz. 

Procedure LineTo2D(x,y-fixed); 
Draws a line to the coordinates x,y while remaining in the 
same z plane. 

Procedure LineTo3D(x,y,z-fixed); 
Draws a line to the coordinates x,y,z. 

Procedure Line2D((dx,dy fixed); 
Draws a line to x+dx, y+dy while remaining in the same z 
plane. 

Procedure Line3D(dx,dy,dz:fixed); 
Draws a line to x+dx, y+dy, z+dz. 

Points 

Function Clip3D(srcl ,src2:Point3D; VAR 
4511 ,dst2:Point):boolean; 
Determines if a line segment is within the viewing 
pyramid. If no part of the line from src1 to src2 falls 
within the viewing pyramid, then Clip3D returns false. 
Upon return, dst1 and dst2 will contain src1 and src2 as 
screen coordinates. Note that the transformation matrix has 
no effect on points passed to this function. If you want to 
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use Clip3D on transformed points, transform them prior to 
calling Clip3D. 

Procedure SetPt2D(VAR pt2D:Point2D; x,y:Fixed); 
Assigns two fixed-point numbers to a Point2D. 

Procedure SetPt3D(VAR pt3D:Point3D;x,y,z:Fixed); 
Assigns three fixed-point numbers to a Point3D. 

Controlling the “Camera” 

Procedure ViewPort(r:rect); 
This routine specifies where to put the image in the 
grafPort. Viewport takes a quickdraw rectangle as its 
argument. 

Procedure LookAt(left,top,right,bottom fixed); 
This routine defines the portion of Graf3D space to map 
into the rectangle set with ViewPort. You can call LookAt 
at any time, but it must always be followed by a call to 
ViewAngle. LookAt sets the xLeft, yTop, xRight, and 
Ybottom fields of the Port3D. It also sets the eye position 
and the hSize and vSize fields as well as hCenter and 
vCenter. 

Procedure ViewAngle(angle:fixed); 
This routine controls the amount of perspective by setting 
the horizontal angle subtended by the viewing pyramid. It 
is the same function provided by changing to a wide-angle 
lens on a camera. Some common settings are 0° (no 
perspective at all), 10° (a telephoto lens), 25° (human eye), 
and 80° (a wide-angle lens). This routine sets the xCotan 
and yCotan fields. 

Transformations 

Procedure Identity; 
Resets the transformation matrix to an identity matrix. The 
ident field of the Port3D is set to true. 

Procedure Scale(xFactor,yF actor,zF actor ;fixed); 
Scale modifies the matrix to shrink or expand by xFactor, 
yFactor, and zFactor. For example 

Scale(3*65536,3*65536,3*65536); 

will make everything three times as big when you draw. 

Procedure Translate(dx,dy,dz:Fixed); 
Modifies the matrix to displace all points by dx,dy,dz. 

Procedure Pitch(xangle:fixed); 
Modifies the matrix to rotate xAngle degrees about the x 
axis. A positive angle rotates clockwise when looking at 
the origin from positive x. 

Procedure Yaw(yangle fixed); 
Modifies the matrix to rotate yAngle degrees about the y 
axis. A positive angle rotates clockwise when looking at 
the origin from positive y. 

Procedure Roll(zangle:fixed); 
Modifies the matrix to rotate zAngle degrees about the z 
axis. A positive angle rotates clockwise when looking at 
the origin from positive z. 

Procedure Skew(zangle fixed); 
Skew modifies the matrix to skew zAngle degrees about 
the z axis. It only changes the x coordinates. This is the 
same effect used by quickdraw to italicize letters. In fact, 
you can obtain an approximation of a quickdraw italic 
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with a zAngle of 15°. A positive angle rotates clockwise 
when looking at the origin from positive z. 

Procedure Transform(src:Point3D; VAR dst:Point3D); 
Transform applies the transform matrix to src and puts the 
result into dst. If the matrix is identity then dst will be the 
same as src. There is a bug in early versions of Graf3D 
which causes problems if you call transform with the same 
Point3D as src and dst. If you run into trouble, simply use 
a second Point3D as the destination and it should work 
fine. 

The Program 

The example program is intended to show the basics of 
working with Graf3D (see fig. 4). It sets up two windows, one of 
which contains a Port3D. A grid and a tetrahedron are drawn in 
the window. By manipulating the three scroll bars, you can rotate 
the images about any of the three axes. The Rotate What? menu 
allows you to change between rotating the tetrahedron or rotating 
all of the three dimensional space. When you are rotating the 
object, the transformation matrix is applied to each point making 
up the tetrahedron. The matrix is then reset to identity and the 
screen is redrawn. When you are rotating space, the matrix is 
changed (using pitch, yaw, and roll) and the screen is redrawn 
without resetting the matrix. In the first instance, the points 
making up the tetrahedron are actually changed. In the second 

Case, no coordinates are changed. This is a subtle distinction that 

eludes many people at first. 

Pascals 
Graf3D Demo was originally written in Lightspeed Pascal, 

which is the version printed here. Since then, I have received a 

copy of Borland's Turbo Pascal and I decided to translate the 

prograam into it as a way of comparing the two language 
implementations; both are provided on the source code disk for 
this issue. The translation process required about ten minutes, 
and the level of compatibility between the two is quite good. 

Turbo Pascal 

To enter and compile the program under Turbo Pascal, you 
simply need to enter the program as listed, enter and compile the 
resource file (using RMaker), and compile to disk. Turbo makes 
it very easy to prodce an application and allows you to link the 
resource file, set the bundle bit, and set the type and creator of 
your program with compiler directives. The compilation process 
is amazingly fast. Running on a Mac+ with a 20 megabyte 

DataFrame SCSI hard disk, it takes approximately six seconds to 

compile and link. It takes about two seconds less to compile to 

memory, whihc allows you to run the program from the Turbo 
environment. The application size ends up at a little over 18K. 
Lightspeed Pascal 
To enter and run the program, you will need to use a text 
editor to enter the resource text, and then run it through RMaker. 

Enter the program in the Lightspeed editor. Only fixmath and 

Graf3d need be declared as all the other standard include files are 

provided by default. Setup the project as shown in fig. 5. 

Be sure to set ThreeD.Rsrc as the resource file under the Run 

Options. Build and save the project as an application. One 

missing piece in Lightspeed is that the creator of a new applica- 


233 


tion is not set correctly for you. In this case you will need to use 
Fedit or SetFile or some other utility to set the creator to SB3D. 
The compile time for Lightspeed is also quit fast. The first 
compile, from a compressed project (admittedly, not a standard 
way to work, other than the very first time you compile some- 
thing), took approximately 55 seconds. The speed of Lightspeed 
shows up when a minor change is made. Changing one line and 
recompiling took only 14 seconds. The final application size was 
11.5K. 

TML Pascal 

I don't have TML Pascal, so I did no comparison, but since 
3DDemo does little that is non-standard, it should run as is under 
TML. You should place the following at the beginning of the 
program: 

{$T APPL !@#$ — 

{$B+ } 

{$L ThreeDRsrc_ } 


Uses MacIntf, FixMath, Graf3D; 
Comparisons 

Both Turbo Pascal and Lightspeed Pascal offer powerful 
integrated programming environments for Macintosh develop- 
ment. Both offer fast compilation (although Turbo is faster), 
separate compilation of units, excellent documentation and low 
price. I would be hard pressed to recommend one over the other. 
I suspect that more experienced users will be more comfortable 
with Turbo with its speedy editor and direct .REL file compati- 
bility, but the interactive debugging and syntax-checking editor 


Options File (by build order) Size 
MacPasLib 15842 


5440 
542 
2014 


MacTraps 
FixMathLib 


Graf SDLib 
R FixMath 
R Graf3D 
R threeD pas 


Fig. 5 LSP Link List 
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with automatic formatting will appeal to beginners and dabblers 
(like me). You would not go wrong to purchase either of these 
products, andat the price, it would almost be worth buying Turbo 
just for the manual. 


( Graf3D Demo 


( by Scott Berf ield 
for MacTutor magazine 


PROGRAM ThreeDDemo; 
($1-) 


USES 

Gref3D, FixMath; 
(MemTypes, QuickDraw, OSIntf, ToolIntf, PackIntf, fixmath, 
gref3d) 


CONST 
object = 1; (flag indicating which we are rotating) 
world = 2; 
hellfreezesover = false; (А boolean for eventloop} 
VIEWwindowID = 32000; (ID of our drawing window) 
INPUTWINDOWID = 32001: (ID of our control window) 
APPLEM = @; (Menu indices} 


8; (Menu resource IDs) 


editID = 
SWITCHID 
lestmenu 
aboutID = 1 
UndoItem = 1; 
cutitem = 3; 
copyitem = 4; 
pasteitem 
clearitem 
Хӛсго1110 
Үӛсго1110 
ZScrollID - 130; 
XMIN = -200; (Limits object space (set with LOOKAT)) 
YMIN = -200; 
ZMIN = -200; 

= 200; 
YMAX = 200; 

= 200; 


0; 

13 

3; (How many menus) 

28; (About alert resource ID) 
(Menu item codes) 


(Scroll bar resource IDs) 


Hn u nu wu ud 
— сл 
N 
со 
`~ 


VAR 
fromupdate : boolean; 
whichcontrol : controlhandle; 
xscroll, yscroll, zscroll : controlhandle; 


myMenus : ARRAY[@..lastmenu] OF menuhandle; 
INPUTWINDOW : windowptr; (pointers to our windows) 
VIEWWindow : — windowPtr; 

Wrecord : windowrecord; (Storage for our windows) 
Wrecord2 : windowrecord; 

gport3d : port3d; (Our 3D grafport) 


XROT, YROT, ZROT : integer; (current scrollbar settings) 
OXROT, OYROT, OZROT : integer; (old scroll bar settings) 
which : integer; (Object or world rotation?) 
XSpacerot, YSpaceRot, ZSpaceRot : integer; 

X0bjRot, YObjRot, ZObjRot : integer; 

Dtetre, tetra : ARRAY[1..4] OF point3d; 


delta : integer; ^ (inc or dec the scroll bars) 
(t crash -------- ) 
PROCEDURE crash; 
BEGIN 

exittoshel!; 
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END; 


BEG 


--------- init --------- 

PROCEDURE init; (set everything up) 
IN 
initgraf CéthePort); 


initgrf3d(@thepor t3d); (required graf3D equivalent) 
InitFonts; 

InitWindows; 

InitMenus; 

TEInit; . 

InitDialogs(@crash); 

InitCursor ; 

FlushEventsCeveryEvent, 9); 


XROT := 
YROT := 
ZROT := 0; 
OXROT := 1 
OYROT := 1; 
OZROT := 1 
XSpaceRot Ü 
YSpaceRot := 0; 

t 0 


0; (Set initial values} 


д 


which := object; 


setpt3dCtetra[2], -1638400, -3276800, 0); 
setpt3d(tetra[3], 1638400, -3276800, 0); 
setpt3dCtetra(4], 0, -4915200, 1638400); 
ОТеіга := tetra; 

; (init) 


(----------- drewvelues ----------) 


PROCEDURE drawvalues; (Draw scroll bar settings as text) 


VAR 


6 
IF COXROT <> XROT) OR COYROT €» YROT) OR COZROT © ZROT) 


text1, text2, text3 : str255; 
trect : rect; 
N 


OR (fromupdate) THEN 


BEGIN (we only draw them if only if something has 


changed) 


setrect(trect, 8, 45, 512, 65); 
setpor tC inputwindow); 
eraserect(trect); 
penpat(b lack); 
textfont(0); 
textsize( 12); 
numtostring(xrot, text1); 
numtostringCyrot, text2); 
numtostring(zrot, text3); 
moveto( 10, 55); 
drawstring(text1); 
moveto(175, 55); 
draws tring(text2); 
moveto(340, 55); 
drawstring(text3); 
OXROT := XROT; 
OYROT := YROT; 
OZROT := ZROT; 
END; 
: (drewvalues) 


sis drawlabels ------------- ) 
PROCEDURE drawlabels; (label the scroll bars} 


VAR 


lebelrect : rect; 


BEGIN 


© 


setrectClebelrect, 0, 0, 512, 24); 
setport( inputwindow); 
eraserect( labelrect); 


The Essential MacTutor, Vol. 3 


( default is to rotate the object) 
setpt3d(tetral1], Ø, -6553600, 0); (tetra vertices) 


textfont(0); 
textsize( 12); (12 point} 
penpatCblack); (make sure we can see it) 
CASE which OF (which labels do we draw?) 
object : 
BEGIN 
тоуеіо(10, 19); 
drewstringC'X Rotation’ ); 
moveto( 175, 19); 
drewstringC'Y Rotation' 2; 
moveto(349, 19); 
drawstring('Z Rotation’); 
END; 
world : 
BEGIN 
moveto(19, 19); 
drewstringC 'Pitch'2; 
moveto(175, 19); 
drawstring('Yaw' ); 
moveto(349, 19); 
drawstring('Roll'); 
END; 


END; (drewlebels) 


(Chicago font) 


ECCI drawgr id ----------- ) 
PROCEDURE drewgrid; (Draw the “space grid”) 
VAR 

i : integer; 


BEGIN (811 coord in fixed point — X by 65536) 


pitch(XSPACEROT % 65536); (rotate space by x value...) 


YAWCYSPACEROT * 655362; (rotate space by y velue...) 
ROLLCZSPACEROT * 65536); (rotate space by z value...) 


(now drew the grid in the newly rotated space) 
moveto3d(-6553600, Ø, -6553600); (-100,0,-100) 
lineto3d(-6553600, Ø, 6553600); (etc...) 
lineto3d(6553600, Ø, 6553600); 
lineto3d(6553600, 0, -6553600); 
lineto3d(-6553600, Ø, -6553600); 
moveto3d(8, 0, -6553600); 
lineto3d(@, 8, 6552600); 
moveto3d(-6553600, 8, 8); 
lineto3d(6553608, 0, 0); 

END; (drewgrid) 


(-------- drawtetra —----—- ) 
PROCEDURE drewtetra; (drew our object) 
BEGIN 
(draw using DTetra which) 
(holds trensformed coordinates) 
(Note that point3D's ere already in) 
(fixed - point ) 


movetosd(Dtetra(1].x, Dtetre(1].y, Dtetra( 11.2); 
lineto3dCDtetre(2].x, Dtetra[2].y, Dtetre(21.2); 
lineto3dCDtetra[3].x, Dtetre(3].y, Dtetra[3].2); 
lineto3d(Dtetre[1).x, Dtetre[11.g, Dtetre[ 11.2); 
lineto3dCDtetre(4].x, Dtetral4).y, Dtetral4).z); 
movetosd(Dtetra(2].x, Dtetra(2].y, Dtetra(2].2); 
lineto3dCDtetra(4).x, Dtetral4].y, Dtetra[41.2z); 
lineto3d(Dtetre(3].x, Dtetra[31.y, Dtetrat31.z); 


END; (drewtetre) 


(pee drewview -----------) 
PROCEDURE drewview; 

(drew the contents of the view window using ) 
(current transform matrix} 

BEGIN 


setport(viewwindow); (where we need to be to drew) 


penpat (black); (ereser color) 


paintrect(theport*.portrect); {erase the screen) 


penpat (white); (line color) 


drewgrid; (draw the plene - space rotated on return) 


drawtetra; 
identity; 


(drew the object) 


(reset the transform matrix ) 
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setportCinputwindow); (Back to the control window!) 
ND; (Drewview) 


—€——— ut =m m ee un m 


drewinpu 
PROCEDURE drewinput; (Drew the control window) 
BEGIN 
setport( inputwindow); 
drawvalues; 
drawlabels; 
DrawcontrolsCinputwindow); 
ND; (drewinput) 


(----------- TRANS -----------) 


PROCEDURE TRANS; (transform on current scroll ber settings) 
VAR 


i : integer; 
BEGIN 
PITCHCXROT * 65536); (x rotation} 
YAWCYROT * 65536); (y rotation} 
ROLLCZROT * 65536); (z rotation) 
IF which = object THEN (if rotating the object...) 
FOR i : 1 TO 4 DO 
BEGIN 
trensformCtetraLi], Dtetra[i12; 
(apply matrix to each point in virgin tetra and) 
END; (store it in the drawing tetra) 
identity; {reset the matrix then draw window) 
drawview; z vim proc controls global viewpoint) 
TRA 


д 


(------------- updateRots ---------- --) 
ГЕО ЕЕ updateRots; (update values from scroll bars) 
EG 
XROT := GETCTLVALUECXSCROLL); (get the current values) 


YROT := GETCTLVALUECYSCROLL); 
ZROT := GETCTLVALUECZSCROLL 2; 


DrawValues; (draw then} 
CASE which OF 
object : (which values need updating?) 
BEGIN 
X0bjRot := XROT; 
YOBJROT := YROT; 
ZOBJROT := ZROT; 
TRANS; 
END; 
world : 
BEGIN 
XspaceRot := XROT; 
YspaceROT := YROT; 
ZspaceROT := ZROT; 
drewview; 
END; 
END; 
END; (updaterots) 
(a dowindows ------------) 


PROCEDURE dowindows; (set up windows and 3D stuff) 
Vrect : rect; 


InputWindow := GetNewWindowCINPUTWINDOWID, @Wrecord2, 
POINTERC- 122; 

xScroll := GetNewControlCOXScrol1ID, InputWindow); 

yScroll := GetNewControl(YScrollID, InputWindow); 

zScroll := GetNewControl(ZScrollID, InputWindow); 

ViewWindow := Ge tNewW indow(V IEWWINDOWID, @Wrecord, 
РОІМТЕКС- 122; 

(set up а 3D grafport (uses reg. grefport for drawing) 

OpensDPor t(@gPor 130); 

setport3d(@gPor t3d); 

viewpor t(viewwindow* .portbits. bounds); 

(set the drawing area to the full window) 

looketCXMIN * 65536, YMIN * 65536, XMAX х 65536, YMAX * 
65536); (set the image space) 
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(set the angle.. 25° = human field of view. ) 
(09=по persp. 88°=fish-eye lens) 
viewengle( 1638400). (25° * 65536) 

END; (doWindows) 


nus 
VAR RE жака (set up menus) 


1: integer; 

BEGIN 
nyMenus [appleM] := GetMenuCeppleID); 
AddResMenu(myMenus [appleM], 'DORVR'); 
myMenus([FileM] := GetMenu(fileID); 
myMenus(EditM] := GetMenuCeditID); 
nymenus [SwitchM] := GetMenu(switchID); 
FOR i := арр1еМ TO lastmenu DO 

inser tMenuCmyMenus[i], 0); 

SetI temIcon(myMenus[@], 1, 195); 
DrawMenuBar ; 

END; (doMenus) 


outne ) 
PROCEDURE om (do about box) 


VAR 
foo : integer; 
BEGIN 
foo := alertCeboutID, NIL); 
END; (aboutne) 
------------ Opplfile --------- 


рр 
PROCEDURE appifile CtheItem : integer); (handle file menu) 
BEGIN 

exittoshell; (they chose Quit) 
ND; (epplf ile) 


———A «кә ewes өш» ewe ae 


Com 
НЕ со. CtheCommand : LongInt); (menu choices) 
theMenu, theItem : integer; 


-------—- Do 


neme : str255; 

RefNum : integer; 

dum : integer; 

blah : boolean; 
BEGIN 


theMenu := hiWord( theCommand); 
theI tem := loWord( theCommand) ; 
CASE theMenu OF 
AppleID : 
BEGIN 
IF CtheIten = 1) THEN 
AboutMe (ebout box) 


getIten(myMenus[eppleM], theItem, name); 


dum := OpenDeskAcc(Name) 
END; (else) 
END; (eppleM) 


FileID : 
ApplFileCtheItem); 


EditID : 
blah := systemEdit(theItem - 1); 


SwitchID : 
BEGIN 
CASE which OF (adjust menuand controls) 
object : (switch to rotating space) 
BEGIN 


which := world; 

setitem(mymenus[switchM], 1, ‘Rotate 
Object’); 

setpor tC inputwindow); 

drawlabels; 
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setctlvalue(xscroll, xspacerot); 

(pick up settings from space values) 

setctlvalue(Cyscroll, yspacerot); 

setctlvalue(zscroll, zspacerot); 

xrot := xspecerot; (update our holders) 

yrot := yspacerot; 

zrot := zspacerot; 

drawvalues; (values for scroll bars) 
END; (object case) 


orld : 

BEGIN (switch from world to object) 
which := object; 
setitemCmymenus[switchM], 1, ‘Rotate 

Space’); 
setport( inputwindow); 
drawlabels; 
setctlvalue(xscroll, xobjrot); 
setctlvalue(yscroll, yobjrot); 
setctlvalue(zscroll, zobjrot); 
xrot := xobjrot; 
yrot := yobjrot; 
zrot := zobjrot; 
drewvalues; 
END; (world сазе) 
OTHERWISE 
END; (case which of) 
END; ‘(switch menu case) 
OTHERWISE 
END; (case theMenu) 
hiliteMenu(a); (turn off menu hilight) 
END; (doCommand) 


рени chagearrow ----------) 
PROCEDURE changeerrow; 
BEGIN 


setctlvalueCwhichcontrol, getctlvelue(whichcontrol) + 
delta); 

updaterots; 
END; 


a ApplMouseDown -----------) 
PROCEDURE ApplMouseDown CtheWindow : windowPtr; 

MousePoint : point); 
VAR 


partcode : integer; 
dummy, temp : integer; 
IN 


IF theWindow = 
BEGIN 
setpor tCinputwindow); 
global tolocalCmousepoint); 
partcode := findcontrol(mousepoint, theWindow, which- 
control); 
CASE partcode OF 
inupbutton : 
BEGIN 
delta z е1 


inputwindow THEN 


dummy : = trackcontrol(whichcontrol, mousepoint, 


@changearrow ); 


indownbutton : 
BEGIN 
delta 
dummy 


@changearrow); 


inpageup : 
BEGIN 
delta 
dummy 


- 10; 


@changearrow); 
inpagedown : 
BEGIN 
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trackcontrol(whichcontrol, mousepoint, 


trackcontrol(whichcontrol, mousepoint, 


delta := 10; 
dummy := trackcontrol(whichcontrol, mousepoint, 
@changeerrow); 
END; 
inthumb : 
BEGIN 


temp := getctlvalueCwhichcontrol); 
dummy := treckcontrol(whichcontrol, mousepoint, 


NIL); 
IF getctlvalueCwhichcontrol) © temp THEN 
updaterots; 
END; 
OTHERWISE 
END; (cese partcode of) 
END; (if) 
END; (epp MouseDown) 
(---------- DoKeyDown ----------- 
ES DoKeyDown (Event : EventRecord); (they pressed а 
key 
VAR 
CharCode : cher; 
BEGIN 
CharCode := chr(Event.message MOD 256); 


IF BitAnd(Event modifiers, CmdKey) = CndKey THEN 
(must of been a commend key, right?) 
DoCommand(MenuKey(CherCode)) (pass it to menu handler) 
END; ( DoKeyDown ) 


( entLoop 
PROCEDURE Event am. 
process those events!) 
VAR 
seveport : GrafPtr; 
GotEvent : boolean; 
NewEvent : EventRecord; 
WhichWindow : WindowPtr; 
Key : cher; 
KeyCommand : LongInt; 
BEGIN 
flusheventsCeveryevent, 0); 
REPEAT 
GotEvent := GetNextEventCEveryEvent, NewEvent); 
IF GotEvent THEN 
BEGIN 


I 
CASE NewEvent What OF 
mouseDown : 
BEGIN 
CASE FindWindow(NewEvent.where, whichWindow) ОҒ 
inMenuBer : 
doCommand(menuSe lect (NewEvent .where)); 
inSysWindow : 
SystemClickCnewEvent, whichWindow); 
inContent : 
app 1MouseDown(whichWindow, NewEvent .where); 
inGoAway : 
IF TrackGoAwayCwhichWindow, NewEvent Where) THEN 


) 
(the neat of the Mac application - 


EGIN 
ExitToShe11; 
inDreg : 
IF whichWindow «€» FrontWindow THEN 
SelectWindowCwhichWindow) 
ELSE 
epplMouseDownCwh i chWindow, NewEvent .where); 
OTHERWISE 
END; (case FWReturnCode) 
END; (case mouseDown) 


KeyDown : 

BEGIN 
doKeyDownCnewEvent); 

END; (Case KeyDown) 
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UpdeteEvt : 


BEGIN 


getport(saveport); (store current grafport) 
setport(viewwindow); (set it to viewwindow) 
beg inupdate(viewwindow); 

drewview; 
endupdate(viewwindow); 
setportCinputwindow); (now do control window) 
beg inupdate( inputwindow); 

fromupdate := true; (draw values if needed) 


drewinput; 
fromupdete := false; (reset the toggle) 
endupdateCinputwindow); 


setport(saveport); (restore the port) 
END;  (updeteEvt) 


OTHERWISE 
END; 


END; амы 


systemTesk; (handle periodic stuff) 


UNTIL HellFreezesOver; 


END; (EventLoop) 


(let it run for a long time) 


( ---------- Main Program ---------------- ) 

BEGIN 
init; (Init toolbox stuff and epp! variables} 
dowindows; (drew windows and setup 3D grafport) 
domenus; (do menus) 
identity; (reset trensformation metrix ) 
drawview; (draw contents of view window} 
drawinput; (draw contents ofcontrol window) 
event loop; (Handle events} 

END. (That's all for now.) 


x 
Resource Ifile: 
x 


3D.rsrc 
???????? 


Type SB3D=STR 


0 
Gref3D Demo by Scott 


Berf ield for MacT 
utor - Version 1.0 


Туре FREF 
1 


9 


APPL 0 
Туре BNDL 


, 15007 
5830 0 
ICN! 
0 15012 
FREF 
0 15007 


Type ALRT 
, 128 
65 95 305 415 
128 
5555 


Type DITL 
8 


д 


5 


x 

BtnItem Enebled 
205 120 237 200 
Gee Whiz! 

* 2 
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“3D Deno”. | StatText Disabled 
5 110 21 200 


Gref3D Demo 


* 3 

StatText Disabled 

38 25 66 285 

Created by Scott Berf ield 
for Mactutor Magazine, 
October 29, 1986 


x 4 

StatText Disabled 

T0 25 166 300 

Use the scroll bars to 
rotate about each exis. 
Whether the entire 3D world 
or just the tetrehedron is 
rotated is set from the 
Rotate What? menu. The 
defeult is to rotete the 
object. 


* 5 

StetText Enabled 

160 25 197 300 
Written in Lightspeed 
Pescal, 

for which I em truly 
thankful! 


Type MENU 
, 138 


Copy/C 
Paste/V 
Clear 


, 129 
File 
Quit/Q 


, 128 
M4 
About Graf3D Demo 
(- 


‚ 131 
Rotete What? 
Rotate Space /R 


Туре WIND 
‚32000 

Graf3D Demo 

42 5 265 506 

Visible GoAway 

g 


/ 
4 


23200 1 
control window 
210 5 338 506 
Visible GoAway 
3 


Type CNTL 

, 128 
X Rotation 
25 10 41 160 
Visible 
16 


0 
0 359 0 


‚ 129 
Y Rotation 
25 175 41 325 
Visible 
16 
1 
0 359 0 


, 130 
Z Rotation 
25 340 41 490 
Visible 
16 


2 
0 359 0 


Type ICN®=GNRL 
‚ 15012 


FFFF FFFO 8000 0018 
8000 801C BFFF FFDE 
BFFC BFDE ВАВ0 95DE 
8560 SADE ВАВ0 800Е 
8558 860Е ВААС 800Е 
8556 9ADE BBFF BDDE 
B422 E2DE B822 21DE 
BFFF FFDE A242 105Е 
C082 O83E FFFF FFFE 
8555 550Е BBFF FEDE 
B7FF FFDE BFFF FFDE 
BFFF FFDE BFFF ҒҒ9Е 
FFFF FF9E FFFF FFDE 
800Ғ EOIE 8003 С01Е 


FFFF FFFC TFFF ЕРЕС 
4000 0038 TFFF FFFO 
x 


FFFF FFFÜ FFFF FFF8 
FFFF FFFC FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFE FFFF FFFE 
FFFF FFFC ТЕРЕ ЕРЕС 
ТЕРЕ FFFB 7FFF FFFÓ 


Туре ICON=GNRL 
,451 

н 

FFFF FFFØ 8000 0018 
8000 801С ВЕЕР FFDE 
BFFC FFDE BABO AADE 
В560 850Е BABS SADE 
B558 95DE BAAC BADE 
B556 955E BBFF BEDE 
B444 E3DE B844 21DE 
BFFF FFDE A084 105Е 
C104 08ЗЕ FFFF FFFE 
8555 55DE BBFF FEDE 
B7FF FFDE BFFF FFDE 
BFFF FFDE BFFF ЕРЕ 
FFFF FF9E FFFF FFDE 
80ІҒ CO1E 8007 801Е 
FFFF FFFC ТЕРЕ ЕРЕС 
4000 0038 ТЕРЕ FFFO 
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Resource Roundup 
Printer Sleuthing 


Weekend diversions 

Normally, the NFL season is considered to last from early 
September until some time in December. However, around here, 
the season has ended early the last few years, as the home team 
has, for all practical purposes, been eliminated a few weeks into 
the season. When San Diego found itself well behind the four 
other teams in its division, I was faced with a question of what to 
do on a Sunday afternoon. (Presumably not a problem at 
MacTutor, since they're a stone's throw from the Anaheim 
Rams, who always seem to have а winning record...) 

About the same time as I gave up on the Chargers, I was 
discussing a design issue with my friends at Silicon Beach 
Software, who recently released their painting/drawing program, 
SuperPaint. The program treats documents prepared for an 
Imagewriter slightly differently than those for a LaserWriter. 
The former are edited at 72 dots per inch, while the latter are 
normally shown at 75 dots per inch, since that is an even multiple 
of the LW's 300 dpi resolution, allowing clean scaling and 
accurate positioning of bit maps and objects. (The LaserBits™ 
uses the actual 300 dpi resolution.) 

Anyway, I was suggesting that it would be nice to pick up 
the target printer from the Chooser desk accessory, rather than 
have a separate option to specify the target printer. The latter 
would mean that a novice user could easily have set the document 
for an Imagewriter while printing on a LaserWriter, or vice versa. 
But, as was pointed out to me, Mac 512 owners witha single 400k 
internal disk can hold System, Finder, SuperPaint (about 140k) 
and either Imagewriter or LaserWriter, but not both. As my 
floppy-swapping days are only a few months remote, I could 
understand the problem. 

Which led me to try to build a dummy LaserWriter driver, 
that would provide “Page Setup” functionality similar to the 
actual driver, but taking up less disk space. 

But since Inside Macintosh doesn’t say how to write your 
own printer driver, I had to dig deeper into the many undefined 
nooks and crannies. In this article, I'll examine the application 
side of printing, while in a future article, I'll examine how a 
printer driver works and give some tips on how to write your own 
printer driver. 

About Printing 

When it comes time to print, what does your program do? 
First, it?s necessary to introduce the concept of a printer driver, 
corresponding to those cute little icons in the System Folder that 
handle whatever printer you're using (Figure 1). How your 
program communicates with those drivers will be discussed 
later. 

If you're a good, compatible Macintosh programmer (i.e., 
your software will work with the next video display), everything 
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CER 


PrintTest Application MacTutor Vol. 3 No. 3 


Joel West 
Western Software Technology 
MacTutor Contributing Editor 


é File Edit 


After PrintDefaultt..) 


iPrUers ion: 2 

prinfo iDev: 0 iURes: 72 

rPoge: (0, 0, 729, 552) 

rPaper: (-32, -30, 760, 582) 

prsti ебеу: 

pr infoPT Dev: 

rPage: (0, 0, 728, 552) 

prXinfo iRoeBytes: 1 
iDevBytes: 0 
bPatScole: 0 


scan: scan 
prJob iFstPage: 1 Ls 
ffromUsr: true 
iFileUc!: 0 pFlileUers: 0 
0019 


: 0 
printX t11: 0002 (2): t3): 0190 


Fig. A Output from our PrintTest Program 


your program draws on the Macintosh screen is done with 
QuickDraw. QuickDraw does everything in terms of GrafPorts, 
which are sometimes served ala carte, but usually part of a full 
course of data provided by the Window Manager or the Dialog 
Manager. 

To print, you just draw everything again, only this time in 
the printer's GrafPort. The printer intercepts the QuickDraw 
operations and does whatever is necessary to translate those 
operations into dots on the printed page. 

Of course, there are some restrictions and limitations on 
what operations should be used or how they should be used, 
particularly on the LaserWriter and LaserWriter Plus. Also, you 
may need to perform certain printer-specific operations, particu- 
larly involving PostScript, as will be discussed later. 

But who does the work? 

The specifications of the entire implementation of printing 
are not well defined. Part of this is because it was a late topic into 
Inside Macintosh; part of it is because some of the information 
is device-dependent, and your program should be designed to 
work with any device. Also, Apple expected it would write the 
only Macintosh printer drivers, although third party drivers have 
been written by independent software developers. 

Normally, it’s somewhat risky to delve below the defined 
specifications of a system such as the Macintosh Operating 
System (the Toolbox isn't much used here), since there's no 


өз: еке : 


Name: Laserwriter | ImageWriter | AppleTalkImageWriter 


Type: PRER PRES PRER 
Creator: LWRT IWRT IWRX 


Figure 1: Printer drivers with Finder 5.3/System 3.2 
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guarantee that these implementation details will remain the same 
in future releases. In fact, the fact that these details are not 
specified may mean that Apple is deliberately reserving the right 
to change the implementation in the future. 

However, there are a few safe exceptions. Sometimes, there 
are de facto standards that exist that are just as ironclad as written 
standards, and it turns out that printing is one such case. 

When you open the chapter on “The Printing Manager” in 
Inside Macintosh, you will see throughout the chapter the nota- 
tion 

[not in ROM] 

Whatthis means is that the entire Printing Manager, as such, 
is in the "glue" that is linked into your application when it 
references printing operations. 

This glue, in turn, references system resources and the 
appropriate printer driver. Figure 2 illustrates the linkages for the 
LaserWriter driver; the AppleTalk ImageWriter driver is similar 
(the ordinary ImageWriter doesn't use AppleTalk.) 

There are no traps to implement these routines and thus, no 
trap routines. For a trap, Apple can issue a new ROM with new 
trap routines, or put a PTCH resource into the System file. 
However, if you link your program this afternoon (or linked it 
two years ago), there is exactly one version of the Printing 
Manager available to your program, despite whatever changes 
Apple might make (or, more accurately, wish it could make). 

That doesn't mean that the printer drivers can't be im- 
proved, or new printer drivers can't be written. Rather, it means 
that the specifications are fixed up to the entry points of the 
printer drivers. 

What happens when your program prints? The Chooser 
desk accessory has previously selected one of the available 
printers, and modified a system resource accordingly. (For a full 
explanation, see Bob Denny's excellent “How the Chooser 
Works," in the July 1986 MacTutor, or the "Device Manager" 
chapter of Inside Mac, Volume IV.) 

The Printing Manager opens the corresponding printer 
driver file. Once upon a time, this had to be on the boot disk. 
Nowadays, it is expected to be in the "blessed" HFS folder, i.e., 
the one with the Finder and System in it. 

The glue code will reference the PDEF (Printer DEFinition) 
code in the printer driver, which does the actual printing and user 
dialogs. For some control calls, it will call the standard DRVR 
named ".Print", which in turns calls the appropriate DRVR in the 
printer driver. 

If you're only printing with your application, not writing a 
printer driver, you're primarily concerned with the Printing 
Manager calls, which will be the subject of the remainder of this 
article. 

User-level interface 

From the user's standpoint, there are three active steps that 
can be taken in conjunction with printing: 

1. Use the “Chooser” to select a printer. This is well covered by 
Denny’s earlier article, so I won't say more here. 

2. Select the "Page Setup..." dialog, referrred to as the style 
dialog (Figure 3). This sets printing characteristics that may 
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your application 


Your printing code Main event loop/ 


menu logic 


Е Print Manager | 
E [пої іп ROM] | 


LaserWriter 
or other 


printer driver 


*Resources in 128k ROM 
in System for 64k ROM 


Device Manager 
Serial Driver (SERD)* 


AppleTalk Driver* 
(DRVR “ATP”, ".MTP") 


Figure 2: Printing resources and hierarchy 


affect the size or layout of the edited text. For example, 
selecting the (nearly obsolete) “US Legal” paper would 
indicate to the application that a taller drawing size is avail- 
able. 

3. Select the “Print...” dialog, or job dialog (Figure 4). This 
prepares a job immediately for printing. 

The user should be able to cancel any of these steps, without 
any affect. And it's not necessary, of course, for the user to go 
through all three steps each time, particularly for similar docu- 
ments (omit step 2) on the same printer (omit step 1). It's also 
possible for an application to allow printing without the third 
dialog, although this should be unusual. 

The user should, however, ALWAYS select "Page Setup" 
after changing the printer using the Chooser, and it even includes 
a message to this effect. This allows your application to assure 
that its current GrafPort is consistent (for page breaks, rulers, 
etc.) with the actual target output device, since your application 
Should already allow for changing the page size, orientation, and 
resolution, which is available to the user in the style dialog. 

There are also several steps that are not seen by the user, but 
must be taken by an application to assure consistency of the 
printing operations. To see how this works first requires exam- 
ining the mechanism used to communicate information about 
how to print a document, the print record. 

Print Records 
Most of the control information for printing is carried by a 
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LLLI NN 


Reduce or 
Enlarge: 


Paper: @ US Letter О Я4 1еїїег 
OUS Legal  OBSLetter 


Orientation 


Figure 3: Page Setup with PrStiDialog() 


Printer Effects: 
D] Font Substitution? 
04 Smoothing? 


LaserWriter «The LU» v3.1 


Copies: | 


Cover Page: @No О First Page © Last Page 


Paper Source: @ Paper Cassette © Manual Feed 


Figure 4: Printing using PrJobDialog() 


TPrint Pascal record (C struct.) Table 1 shows a psuedo- 
declaration of the TPrint record. TPrint is normally used through 
a TPPrint pointer or a THPrint handle. 

This is only a psuedo-declaration; each of the embedded 
records are actually declared as new types (shown in the com- 
ments). For clarity’s sake, these embedded records are shown 
inline, since only two fields are directly part of the TPrint record, 
one of them the filler. The enumerations are also shown inline. 
Also not normally shown are the offsets, which are essential if 
you have to reverse engineer a TPrint from a hex dump, or want 
to debug application printing code at the assembly level. 

The final field is a filler to round the record out to an even 
120 bytes — the amount of memory returned by 
sizeof (Tprint) in both Pascal and C, and the amount of 
memory you need to reserve in your document for holding the 
values. (See, for example, the discussion of the MacWrite file 
format in Technical Note #12.) Why isn't the print record stored 
as a resource? It would have made sense, and there's even a 
resource type used by a few applications (PREC), but most 
programs — including Apple's — include it in the data fork. 

For our purposes, there are several fields of interest. As- 


suming the declaration 
ph: THPrint; { Pascal) 
THPrintph; /C*/ 


then, the ph^^.prInfo((*ph)-»prInfo inC)subrecord 
contains most of the information the application will access 
directly. In particular, the program will want to know the 
horizontal and vertical resolution used for drawing, so that it can 
put up, for example, the appropriate rulers. (MacDraw worries 
about this, but MacWrite just cheats and always assumes the 
same resolution for ruler purposes.) 

Most significantly, the field ph^^.prInfo.rPage 
gives the size of the drawing area, in units of the horizontal and 
vertical resolution. This works out to be 10.44 inches vertically 
by about 8 inches foran Imagewriter using US Letter paper. (Tall 
adjusted changes the horizontal resolution, but the equivalent 
measurement of rPage in inches remains the same.) 
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Pages: © All Orrom[ Jj | 


For the LaserWriter and LaserWriter 
Plus, rPage works out to be 10.11 inches by 
7.66 inches using US Letter paper. This size 
is odd because there is not quite enough RAM 
on either model to image a full-page bit map. 
The vertical .33 inches is a missing line in 
MacWrite, while MacDraw rounds the hori- 
zontal 7.66 down to the nearest half inch, 
breaking the display into multiples of 7.5 
inches. 

The size of ph^^.rPaper gives the 
size of the actual paper, since none of the 
existing printers allow you to print to the 
margin. This is slightly wider on all four sides 
of rPage. As shown in Figure 5, the local 
coordinate origin (as QuickDraw terms it) for 
rPaper is the same as for rPage, in that 
(0,0) is the upper-left corner of the actual 


[OK | 


drawing area. As youareusually concerned with rPage and not 
rPaper, this is a reasonable choice. Don't assume that there 
will always be a margin, since it's conceivable that гРарег 
could be the same as граде: for example, “Чо Gaps Between 
Pages" on the ImageWriter sets the top and bottom coordinates 
of the two rectangles (for US Letter) to O and 792, respectively. 

Another field of interest for our purposes is the byte that tells 
you which printer you're using. The upper half of the 16-bit word 
ph^^.prStl.wDev gives the device you're using. Why the 
upper half of a word is used and not a separate field, I don't know, 
but the lower half includes other information about the printing 
characteristics, as shown in Table 2. (The “W” is not capitalized 
in the name of the original Imagewriter, according to Apple 
product documentation, but all the other Writers are capitalized.) 

AS you can see, except for the use of fPortrait, the interpre- 
tation of the lower byte is very device-dependent, so you 
shouldn't use these values without first checking the device field 
to understand its interpretation (and if the upper byte is 4 or 
greater, don't try to intrepret the lower byte!) 

Officially, your application is supposed to ignore much of 
the TPrint information — used internally by the printer driver — 

in particular the rest of prSt1 and the entire prInfoPT. 
However, as shown in Table 3, the device-dependent 
prStl.feed indicates how the paper is being fed, which may 
affect, say, some of your user instructions. 

Finally, the pr Job does have several fields it’s officially ok 
for your application to look at, such as the page range. The field 
prJob.bJDocLoop, shown in Table 3, indicates the steps 
your application needs to take to print the document, as discussed 
in “To Spool or not to Spool?” below. 

When 72 = 80 # 75 

The fields ph^^.prInfo.iHRes and 
ph^^.prInfo.iVRes indicate the horizontal and vertical 
resolution of the print device in dots per inch. This allows your 
application to translate the rPage pixel units into actual inches 
(centimeters, etc.), such as when you display aruler on the screen. 

For the ImageWriter, the value of iVRes is always 72 dpi. 
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TPr int: 


aN ~~] 


8-15 
16-23 rPaper: 
24 


2890 


82-119 printX: 
END; 


RECORD 

iPrVersion: INTEGER 

prinfo: RECORD 
iDev: INTEGER; 
iVRes: INTEGER; 
iHRes: INTEGER; 
rPage: Rect; 
END; 

Rect; 

prSt!: RECORD 
wDev: INTEGER; 
iPageV: INTEGER; 
iPegeH: INTEGER; 
bPort: CHAR; 
ded (feedCut, feedFanfold, feedMechCut, Геейдіһег); 

ND; 

prinfoPT: RECORD 
iDev: INTEGER; 
iVRes: INTEGER; 
iHRes: INTEGER; 

гРаде: Rect; 


END; 

prXInfo: RECORD 
iRowBytes: INTEGER; 
iBandV: INTEGER; 
iBandH: INTEGER; 
iDevBytes: INTEGER; 
iBends: INTEGER; 
bPatScale: Byte; 
bUlThick: Byte; 
bU10ffset: Byte; 
bUlShadow: Byte; 
scan: CscenTB,scanBT, scenL R, scanRL 5; 
bXInfoX: Byte; ( filler ) 


END; 
prJob: RECORD ( TYPE TPrJob ) 
iFstPege: INTEGER; ( default 1) 
iLstPage: INTEGER; ( default 9999 ) 
iCopies: INTEGER; ( not used by LaserWriter ) 
bJDocLoop: CbDraftLoop, bSpoolLoop); 
fFromUsr: BOOLEAN; 
pIdleProc: ProcPtr; 
pFileNeme: StringPtr; 
iFileVol: INTEGER; 
bFileVers: Byte; 
bJobX: Byte; 


( TYPE TPrInfo ) 


( dots per inch ) 
( dots per inch ) 


( TYPE TPrSt1 ) 
( printer type in upper byte ) 


( TYPE TPrInfo ) 


( TYPE TPrXInfo ) 


( filler ) 


END; 
ARRAY(1..19] OF INTEGER; ( in C, 0..18) 


TPPrint = ^TPrint; ( the pointer ) 
THPrint = “TPPrint; ( the handle ) 


Table 1: Contents of a Print Record 


Lower byte 
yalue use 


hi resolution 
portrait orientation fPortrait 
square pixels 
zoomed 2x 


16 


field ImageWriter 
fHiRes Quality: Best 
fSqPix Tall Adjusted: on 
f2xZoom 50% Reduction: оп — 
fScroll — — 


Table 2A: Decoding the value of ph^^.prStl.wDev 
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LaserWriter 

Font Substitution: on 
Orientation: (portrait) Orientation: (portrait) 
Smoothing: on 


If you are using the landscape printing orientation, or if 
you select the "Tall Adjusted" checkbox for portrait 
orientation, then the value of iHRes will also be 72 dpi, 
and circles will come out round, etc. Tall Adjusted 
should be default for any graphics program. 

However, the default selection for the ImageWriter 
is 80 dpi horizontal resolution. The original fonts were 
designed for this resolution, and it is slightly faster. If 
you try portrait printing with and without Tall Adjusted, 
using a bit-map font (Geneva, New York), you'll see that 
the slightly higher horizontal resolution produces a no- 
ticeably better result. 

So much for that. Now suppose you were printing 
on the LaserWriter, which has a 300 dpi resolution. 
Wouldn't you expect iHRes and iVRes to return 300? 
They don't. How about 75, exactly 4:1? Nope. 

Instead, the LaserWriter returns 72 for each, the 
same as the ImageWriter in Tall Adjusted (except for 
page size), and thus allowing earlier programs designed 
for the ImageWriter to always work (like MacWrite's 
fixed-size ruler.) 

The LaserWriter scales all coordinate locations by 
300:72, which is notan integral value. However, it prints 
all bit maps at 300:75 (4:1) scaling. This means that a 
square drawn 72 pixels long (in QuickDraw coordinates) 
will come out 300 pixels on the LaserWriter (with 
LaserWriter driver 3.1), while a 72x72 bit map will come 
out as 288 pixels long, or 4% smaller than 300:72. 

If the LaserWriter instead reported its resolution as 
75 dpi, then everything would be hunky dory, since both 
coordinates and bit maps would be scaled 4:1. (You 
could also produce bit maps at 300:75, which means 
every 24th pixel would be 5x5 instead of 4x4 Laser- 
Writer dots.) 

One more oddity. Suppose you enter “50%” in the 
Reduce box for your LaserWriter, or check “50% Reduc- 
tion" for the ImageWriter. You might think that would 
increase your resolution to 144, since that's the number 
of QuickDraw points now printed on each inch of an 
output page. 


Wrong. Theresolution remains the 
same (again, probably, to assure com- 
patibility for those early programs that 
make erroneous assumptions). Instead, 
your paper size is reported as being 
twice as large! This works out to be 16 
x 20.88 or 15.33 by 20.22 respectively. 

To catch this 50% reduction, the 
field prSt1.wDev has bit £2xZoom 
set for the ImageWriter, while field 
prXInfo.iBandH contains the ac- 
tual reduction (or enlargement) percent- 
age for the LaserWriter only. 

You could probably use this to 
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Upper byte 


0 


— screen 
1 bDevCltoh 


Imagewriter, ImageWriter Wide 
ImageWriter Il (with or w/o AppleTalk) 
DaisyWriter (old ГОР) 

LaserWriter, LaserWriter Plus 


2 55 
3 bDevLaser 


Table 2B: Decoding the value of 


correct your rulers (to the actual size) for these two printers, but 
it wouldn't help you for future printers, since Apple hasn't 
indicated an official mechanism for determining the actual re- 
duction or printed page size on any printer. (Is anyone in 
Cupertino listening?) It's probably just better to document for 
your users a consistent treatment for all printers (the false sizes) 
until this is fixed. 
Printing steps 

Figure 6 shows a flow chart of the steps your program will 
typically take in using the TP rint record. An application does 
not (usually) change any of the TP rint fields directly, instead 
using Printing Manager routines (which in turn call the appropri- 
ate driver) to do the actual work. However, the modified 
TPrint should be saved by your application with the document 
for future retrieval. 

When you start a new document, you should allocate a 
relocatable TP rint, as іп 


ph:= TPrint(NewHandle(SIZEOF(TPrint))); 
ph = (TPrint)NewHandle(sizeof(TPrint)); 


for Pascal and C, respectively, and then pass the handle to 
PrintDefault. This routine sets the default values for the 
currently selected printer. If you have an existing TPrint, the 
routine PrValidate will fix up any fields for consistency with 
the currently selected printer. 

This handle is passed around to most of the Printing Man- 
ager Calls. It’s omitted from the actual printing operations since 


PrOpenDoc stuffs in the GrafPort . 
(TPrPort, actually) a copy of the handle. 
When you start printing, you can specify 
your own background procedure that will run 
whenever printing is in progress, but the Printing 
Manager has some idle time on its hands. This is 
normally used to put up several pushbuttons, and 
allow the user to abort printing by pushing a 
button (rather than the Command-period pro- 
vided by the Prinüng Manager default proce- 


dure.) To use this option, set 
prJob.pIdleProc to the address of your field 
procedure. 


Table 4 shows the standard results obtained 
from the style and job dialogs for the Imagewriter 
and the LaserWriter. The boolean expressions 
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value use 
Draft quality 


feedCut 

feedFanfold 
feedMechOut — 
feedOther — 


are shown in C form for compactness. 

Note that several fields are very device-dependent. The 
ph^^.prXInfo.iBandH is used to indicate the reduction in 
the LaserWriter, while its original interpretation (used by the 
ImageWriter) has to do with the horizontal printing band size. 

After any routine, there may be an error, so you should 
check the routine PrError for it. If you're a speed freak, the Pascal 
reference 


CONST 
PrintErr = $944; 
TYPE 
WordPtr « ^INTEGER; 


IF WordPtr(PrintErr)^ <> noErr 
THEN 


or the C code 


#define Word short /* 16-bit integer */ 
#define PrintErr *((Word *) 0x944) 


if (PrintErr l= noErr) ... 


will grab it directly. 

To spool, or not to spool? 

The previous flow chart described the easiest case of print- 
ing. IfbJDocLoop equals bDraft Loop (0), that's all there is 
to it; the QuickDraw operations are directly translated into 
printer commands. This corresponds to the low-quality (Draft) 
ImageWriter output, which uses the printer’s ASCII output 
capabilitites, but necessarily ignores any graphical primitives. 

Draft mode also is used for any quality for the LaserWriter, 
since the PostScript capabilities and built-in logic can produce 
the graphics directly. 

However, the miracle of the original Macintosh and 
Imagewriter is that a simple nine-pin dot-matrix printer could 
produce such results. In order to do so, the Macintosh’s Quick- 
Draw routines must be used to convert the graphics operations 
into a simple bit map, which is then output a line at a time to the 


Value of ph^^.prJob.bJDocLoop: 


bDraftLoop Draft Quality all 


Spooled printing bSpoolLoop Faster, Best quality 


Value of ph^^.prStl.feed: 
LaserWriter 
Manually-fed cut sheet — 
Continuous, sheet feeder — 


Bin feeder 
Manual feed 
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1/4" 


(0,576) 


irPage 
| drawing area 


rPaper 
physical paper 


2 US Letter 


Tall Adjusted 
(72 dpi x 72 dpi) 


(752,0) (752,576) 


Figure 5: GrafPort for ImageWriter printing 


printer. 

This requires a lot of memory, and was even more of a 
miracle on the 128k Mac. Even more memory may be required 
by LaserWriter printing, for both the RAM-based AppleTalk 
drivers on 64k ROM machines, and for the conversion from 
QuickDraw to PostScript, as discussed in the next section. 

As a consequence, the standard advice to assure enough 
memory for printing is: 

• Put printing in its own segment (or in the main segment, if 
memory isn't otherwise a problem.) 

* Unload every other possible segment prior to printing. 

• Do everything you сап to avoid heap fragmentation. 

The actual printing in spool mode is handled by a call to 
PrPicFile after the call to PrCloseDoc. The spool image 
may be in memory (if available) or on disk in the blessed folder. 

The field prJob.iCopies may be set by the 
PrJobDialog for the number of copies to print. PrPicFile 
handles multiple copies of each page automatically; as shown 
later in the example, the application is responsible for sending 
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1/4" 


Мм 


multiple copies to the driver when printing in 
draft mode. 

However, the LaserWriter firmware has a 
setting (the PostScript #copies...showpage) to 
churn out multiple copies, so it's not necessary 
for your application to send multiple copies to 
the LaserWriter (which always uses draft 
mode.) To provide compatibility, the PrJobDia- 
log places the copy count in iRowBytes and 
"hides" any indication of multiple copies from 
the application by always setting iCopies to 
l. 


) 1/2" 


Postscript on PostScript 

If you bought an early application in 1984, 
then you may have been pleasantly suprised to 
find out that it would print on an Apple Laser- 
Writer released a year later. Any program that 
uses normal QuickDraw operations should 
work with any Apple printer, now or in the 
future. 

If you know anything about printing, then 
you're probably aware that the LaserWriter and 
LaserWriter Plus have their own printing proto- 
col: PostScript from Adobe Systems, Inc. The 
issue of PostScript complicates everything said 
so far. 

PostScript is, as previous MacTutor ar- 
ticles have noted, far more versatile than Quick- 
Draw (see “Laser Print DA for PostScript” by 
Mike Schuster, February 1986.) Any Macin- 
tosh program that prints to either printer will 
eventually require PostScript commands to dis- 
play an output. 

Normally, the LaserWriter driver does this 
for you. It translates your QuickDraw com- 
mands into a special set of abbreviated codes. 
These are usually two- and three-letter abbreviations, while the 
standard PostScript normally consists of words or recognizable 
abbreviations (get, currentgray). 

A PostScript program (the Laser Prep file) suitable for 
interpretting these codes is automatically downloaded by the 
driver when the printer is first used after it has been reset. This 
currently works out to be about 25k of PostScript. These codes 
take advantage of only a subset of PostScript corresponding to the 
QuickDraw view of graphics. 

If you want to see the PostScript produced for a document, 
select “Print...” and make the appropriate PrJobDialog selec- 
tions. Hold down Command-F and mouse-select the OK button; 
the LaserWriter status dialog will indicate that the PostScript is 
being saved. You will find a text-only file (MDS Edit as the 
creator) in the current default directory. You can also use 
Command-K in the same way to include the Laser Prep before the 
actual document. 

You don’t need to have an actual LaserWriter handy to 
obtain the PostScript dump. All you need is the LaserWriter 3.1 
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em... m 


sets ph^^ 


PrValidate(ph) uc 


modifies ph^^ 
PrStlDialog(ph) 


modifies ph^^ 


PrJobDialog(ph) : per 


port := 


V» PrOpenDoc(ph,... [——— uses ph^^ 


| PrintDefaut(ph) 


modifies ph^^.prJob 


PrOpenPage(port) 


and there are also problems with Apple's 
implementation of the interpreter. Version 
3.1 of LaserWriter is vastly superior to its 
predecessors, and you can bet that further 
improvements (fixing the notorious 496 
shrinkage of bit maps!) are a high priority 
for Apple in keeping its hold on the desktop 
publishing market. 

The official way to handle all this is to 
use QuickDraw. Apple is not going to 
abandon QuickDraw, and has incorporated 
it into its Apple IIGS as part of a long-term 
plan to merge its two computer lines. If you 
want to do fancier stuff, you can include 
some additional PostScript features (rotated 
text) in your QuickDraw picture, or even 
merge direct PostScript if necessary: see 
Macintosh Technical Note #91: “Optimiz- 

ing for the LaserWriter.” 

About the example 

Finally,I'veincluded P rint Test,an 
application that analyzes the contents of 
TPrint fields. Itallows youtoselect various 
printing dialog options, and see the effect on 
the TPrint record. Since it is a printing 
demo, it naturally allows you to get a perma- 
nent record by printing out the result. 

Since this column documents the basic 
Macintosh technology, I took a few days to 
convert my original C prototype to MPW 
Pascal, not a trivial chore, due to syntax 


QUIT 


Another SetPort(port) differences, and because of Pascal's abys- 
page? (draw the page) mal (lack of) formatting utilities. 

PrClosePage(port) [Note: Due to the fact that MPW is still 

in limited release through APDA and few 

people have it, we have also made available 

a Lightspeed Pascal version, which is 

PrCloseDoc(port) ph: THPrint; printed here. Both the MPW and the LSP 

port: TPrPort; {GrafPtr} versions are also available on the source 


Figure 6: Simplified printing loop (draft & LaserWriter) 


driver (and Laser Prep), and to select the LaserWriter with the 
Chooser. 

More exotic LaserWriter printing schemes are possible for 
higher performance, at great risk of future compatibility. Page- 
maker uses its own version of Laser Prep, which can give other 
programs problems. Some programs output direct PostScript, 
since it is assumed that only the lowly ImageWriter is without 
that capability. However, what if Apple should (as rumor has it) 
introduce a new low-cost laser printer without PostScript? 
You'd be stuck with limited (or no) graphics performance on this 
new high-resolution device. 

Needless to say, using QuickDraw limits your flexibility, 
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code disk for this issue (See the MacTutor 
mailorder store). The LSP version should be 
readily transportable to any Pascal system 


for the Mac. MPW uses anumber of useful utilities and functions, 
but they are generally not supported by other systems, making 
porting more difficult. There should be no problem going from 
LSP back to MPW however. -Ed] 

The C original used sprintf, a nifty general-purpose 
routine that will format many fields into a string. For Pascal, I 
wrote a StringFormat unit to provide a subset of these capabili- 
ties, and each sprintf has been replaced by a Pascal call for each 
field. 

I started with my favorite example program, File by Cary 
Clark of Apple, a simple text editor. About two thirds was 
concerned with windows, scrolling, controls, etc. and wasn't 
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ImageWriter 


PrStiDialog 
Setting How to te11§ 
Paper: US Letter SubPt(rPaper . topleft,rPaper .botRight) 
is = 8.5" by 11" or 11" by 8.5" 
Tall Adjusted: off! I(wdev & FSqPix) 
50$ Reduction: off I(wdev & f2xZoom) 
No Gaps Between Pages: off (CrPaper.top == 0) && 
(rPaper .bottom == 
pr Info.rPage.bottom) 
Orientation: Cportrait tt Cwdev & fPortrait) 
PrJobDialog 
Quality: Fester C!Cwdev & fHiRes) && 
(prJob.bJDocLoop == bSpoolLoop)) 
Page Range: A11 (CprJob. iFstPage == 1) && 
(prJob.iLstPage == 9999)) 
Copies: 1 (prJob.iCopies == 1) 
Paper Feed: Automatic (prStl.feed == feedFanfold) 


t Also, prInfo.iHres-s80 
tt Of course, Cprinfo.rPage.bottom > prInfo.rPage.right) 


LaserWriter 
PrStiDialog 
Setting How to tellg 
Paper: US Letter SubPt(rPaper . topleft,rPaper .botRight) 
is 9 8.5" by 11" or 11" by 8.5" 
Font Substitution: on (wdev & fHiRes) 
Smoothing: on (ндеу & fSqPix) 
Reduce or Enlarge: 1004! CprXInfo. iBandH == 100) 
Orientation: Cportrait)tt (wdev & fPortrait) 
PrJobDialog 
Copies: 1 (prJob.iRowBytes == 1) 
Pages: All CCprJob.iFstPage == 1) && 
(prJob.iLstPege == 9999)) 
Cover Page: No CprXInfo. iBandV == 0) 


Paper Source: Paper Cassette (prStl.feed == feedMechCut ) 


* This modifies prInfo.rPage and rPaper, but not prInfo.iVRes or 
prinfo.iHRes, meaning that the size of the “page” Cin inches) actually 
changes instead of the resolution! 

tt Of course, Cprinfo.rPage bottom > prinfo.rPage.right) 


§ C conditional expression; for Pascal, use these equivalents: 


| NOT 


&& AND 
% BitAnd() 


Table 4: Default dialog settings for ImageWriter and LaserWriter 


relevant, so I took it out. (If you were building an actual application, you 
might want to get a copy of File and add some of this code back in.) 

File did include a main event loop, basic initialization, a first approach 
towards memory management. It displays text in a screen window using 
TextEdit. PrintTest adds its analysis lines to the end of a TextEdit record, and 
scrolls up the display so that the last line is always visible. 

The printing logic had to be totally rewritten. File recalculated the line 
breaks for printing, since it wrapped text (both displayed and printed) to the 
size of the destination rectangle, while in this example, line breaks are only 
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at returns. 

File also had an elaborate scheme for back- 
ground printing, using an idle procedure. 
PrintTest puts up a dialog box (showing prog- 
ress reports) advising the user of the default Com- 
mand-period option. 

More important, however, are the new features 
necessary for the printing loop. The version of File 
(v1.1, May 85) used Text Box to print each page. 
TextBox is very slow on the LaserWriter, since it 
uses EraseRect. PrintTest uses DrawText 
for each line of text instead. 

The example will check for a printing error, and 
puts up an alert indicating the error by number. Ina 
real application, you would use a resource to look up 
the text of the error messages. Note that the logic 
ignores certain psuedo-errors, such as a user-re- 
quested abort. Also note that resources are used for 
the alert and progress strings, since an international- 
izable program should include all literals as re- 
sources. 

PrintTest includes a page number centered 
at the top of each page. Since the output is so 
repetitive, I added this so I could debug my page 
selection logic. 

Finally, PrintTest shows an example of 
how to save time printing a portion of a large docu- 
ment. With a little extra effort, you can check 
directly to see which pages the user wants from the 
prJob information, and print only those pages. 

Suppose the user requests printout starting at 
page 11 of a 20-page document. You would have 


prJob.iFstPage = 11 
prJob.iLstPage - 9999 


since 9999 is currently the default last page number 
set by PrJobDialog. The application would then 
pass all (20) pages to the Printing Manager, which 
would not print the first 10 pages, as counted by calls 
to PrOpenPage. If your application always prints 
all pages, the Printing Manager select only those 
indicated. 

However, your program can skip the unneces- 
sary pages. First, change the values to 


1 
9999 


prJob.iFstPage 
prJob.iLstPage 


so the Printing Manager will start printing from the 
first page. Your application should start with page 
11 and continue through to theend. iLstPage can 
actually be set to any value greater than or equal to 
10 (20-1141), since the application will only send 10 
pages. 


© The Essential MacTutor, Vol. 3 


| PrintTest keeps two separate TPrint records. One is 

used for analysis purposes, while the other is used for printing the 
analysis. Two sets of commands are provided on the File menu, 
one set that does the actual Page Setup and Print operations, and 
one that simulates these operations and analyzes the new con- 
tents of the TPrint. 

PrintTest supports desk accessories, so you can use the 
Control Panel and Chooser da’s. Even if you don’t have all the 
printers, if you have the appropriate drivers in your System 
Folder, you can use PrintTest to try out the corresponding 
dialogs. For example, if you need to know the exact size of an A4 
(European) page for both the LaserWriter and ImageWriter, 


PrintTest will show that and provide a permanent record. 


Lightspeed Pascal Version 
PROGRAM PrintTest; 
($1-) 


( Examine end display TPrint record values.) 

( Written by Joel West , Western Software Technology) 

( LS Pascal source conversion by D. Smith ) 

(Begun with an underlying skeleton , using part of ) 

(an example from Apple User Education) 

(File : Example code for a text editor by Cary Clark , ) 
(Macintosh Technical Support Version 1.1 May 13 , 1985 ) 


(Portions copyright € 1986 by) 
( Joel West , Western Software Technology, } 
( for use by MacTutor. ) 


( A document in this program (built by TextEdit) is used to) 
( display the contents of a modified TPrint record.) 

{ There are Job & Style dialogs for modifying the) 

( record, and for actually printing out the document.) 


USES 
MacPrint, MyGlobals, StringFormat, DumpTPrint, 
Windows, Printing, SetupMenus; 


(------------Alert for About.---------------- --) 
oye About ThisProgram; 


itemhit : INTEGER; 
hand : StringHandle; 
BEGIN 
DialogueDeact ivate; 
hand := GetString(STR_id); 
ParamTextChand**, '', '', | 
itemhit := NoteAlertCALRT_about, NIL); 
END; (AboutThisProgrem) 


(---------------Handle menu commend------------) 
xr m DoCommand Ccommandkey : BOOLEAN); 
AR 
daname : Str255; 
refnum, theMenu, theItem : INTEGER; 
menuResult : LONGINT; 
deedit : BOOLEAN; 
BEGIN 


IF commandkey THEN 
menuResult := MenuKey(theChar ) 
E 


menuResult := MenuSelect(myEvent . where); 
theMenu := HiWord(menuResult); 
theItem := LoWord(menuResult); 
CASE theMenu OF 
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appleMenu : 


BEGIN 
IF theltem = 1 THEN 
AboutThisProgren 
ELSE 
BEGIN 


GetItem(nyMenus[appleMenul, theItem, дапәле); 


refNum := OpenDeskAcc(daname ) 


BEGIN 

CASE theltem OF 

newItem : (New ) 
OpenAWindow; 

closeItem : (Close ) 
CloseAWindow; 

stlitem : (PrSt1Dialog.. ) 

BEGIN 
PrOpen; 
DialogueDeectivate; 
IF PrStiDialog(wdh^^.theTHP) THEN 


DumpPr intC'After PrintStlDialogC.2', 
wdh**. theTHP); 


PrClose 
END; 
jobItem : (PrJobDislog.. ) 
BEGIN ( just modifying TPrint ) 
PrOpen; 
DialogueDeactivate; 


IF PrJobDialogCwdh**.theTHP) THEN 
DumpPr intC'Af ter. PrJobDialogC..2', 


«Оһ theTHP); 


PrClose 
END; 
setupItem : (Page Setup.. ) 
BEGIN 

PrOpen; 

DialogueDeactivate; 

IF лш THEN 


END; 
printItem : (Print ) 


printFleg := E (Do it after segs unloaded) 


quitItem : (Quit 
doneFlag := TRUE; 
OTHERWISE (required for 15Р!) 
BEGIN 


END; 
END (CASE (һе tem} 
END; (fileMenu) 
editMenu : 
deedit := SystemEditCtheitem - 1); 
OTHERWISE 
BEGIN 


END; 
END; (CASE theMenu) 
HiLiteMenuC0); 


END; (DoCommand) 


SS The main event loop--------------) 
PROCEDURE MainEventLoop; 
VAR 


tempwindow : WindowPtr; (the find window) 


BEGIN 


REPEAT 
SystenTask; 
IF printFleg THEN 
BEGIN 
Ргдреп; 
DoPr int ing; 
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PrClose 
END; 
IF GetNextEventCeveryEvent, myEvent) THEN 
BEGIN 
CASE myEvent.what OF 
mouseDown : 


BEGIN 
CASE FindWindow(myEvent where, tempwindow) OF 
inMenuBer : 
DoCommand(FALSE ); 
inSysWindow : 
SystemClickCmyEvent, tempwindow); 
inDrag : 
DragWindow€tempwindow, myEvent.where, dragRect); 
inContent : 
SysBeep( 1); 
inGoAway : 
IF TrackGoAway(tempwindow, myEvent.where) THEN 
CloseAW indow; 
OTHERWISE 
BEGIN 


END; 
END (CASE FindWindow ) 
END; (of mouseDown ) 
keyDown, autoKey : 
BEGIN 
theChar := CHR(BitAnd(nyEvent .message, charCodeMask)); 
IF BitAnd(myEvent modifiers, CmdKey) © 0 THEN 
DoCommand( TRUE) ( do menu equivalent ) 
ELSE 
SysBeep( 1); 
END; (of keyDown) 
activateEvt : 
MyActivate; 
updateEvt : 
DrawW indow; 
OTHERWISE 
BEGIN 


( no typing allowed! ) 


END; 
END; (CASE Event .what ) 
CheckW indowMode ; 
END (of true GetNextEvent) 
ELSE IF CmyEvent.what = nullEvent) AND doneF lag AND 
(FrontWindow <> NIL) THEN 
CloseAWindow; 

( leave lots of memory available, so unload everything ) 
UnloadSeg(@Swr ite); (segment StringFormat) 
UnloadSeg(@Pr intL ine); (segment DumpTPr int) 
UnloadSeg(@OpenAWindow); (segment Windows) 
UnloadSeg(@DoPrinting); ^ (segment Printing) 


қ UNTIL doneFlag AND (FrontWindow = NIL); 


PROCEDURE crash; 
BEGIN 
ExitToShel1; 
END; 


(-------------Memory initialization & Setup --------- ) 
PROCEDURE SetUpMemory; 
BEGIN 
InitGref CéthePor t); 
InitFonts; 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogsCécrash); 
InitCursor; 
MexApplZone; 
MoreMasters; 
MoreMasters; 
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MoreMasters; 
MoreMasters ; 


FlushEventsCeveryEvent, 9); 


wetchHdl := GetCursor(WatchCursor ); 
HNoPurgeCHandleCwatchHdl)); 


printHd] := THPrintCNewHendle(SizeOf CTPrint))); 

PrOpen; 

PrintDefeult(printHd12; (one used for actual printing ) 
PrC lose; 


Linebuff := ''; (init required for LSP} 
END; 


(------------Ивіп progran-------------} 


BEGIN (main program ) 

SetUpMemory; 
SetUpMenus; 
SetUpW indow; 
unloadseg(@SetUpMenus ); 
MainEventLoop; 
SetCursor (watchHd1**); 

END. (main) 


UNIT MyGlobals; 
INTERFACE 


MacPrint; 


TYPE 

WordPtr = “INTEGER; 

MyWindMode = (NullMode, OpenMode, DAMode); 

WindowDete = RECORD ( only one handle in wRefCon ) 
theTE : TEHendle; ( for TextEdit record ) 
ae :  THPrint; — ( the TPrint we are analyzing ) 

WindowDetePtr = “WindowData; 

WindowDateHendle = “WindowDatePtr; 


CONST 
( Change these to suit your teste ) 
myStdFont =monaco; 
myStdSize =9; 
myHdgFont =systemFont; ( aka Chicago ) 
myHdgSize = 12; 
( menus 
app leMenu = 1; 
fileMenu = 2 
newItem = 1 
closeItem = 2; 
stiIten = 4 
jobI tem = 5 
setuplI tem =7; 
printItem =8; 


quitItem = 10; 

lestFileItem = 10; 

editMenu = 3; 

lestMenu = 3; (Number of menus) 
( Resources ) 


ALRT_about = 256; 
ALRT_printerr = 257; 
DLOG_printing = 258; 
STR id = 256; 
STR_pagehead = 257; 
STR.prepare = 300; 
STR.printing = 301; 
STR_spooling = 302; 
STR.of = 303; 


( About.. message ) 

( report printing error ) 

( printing status dialog ) 
(ebout message) 

( pege heading ) 

( messages for printing status ) 
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STR-prspool = 304; 
STRN. scan 2256; 
ӨТЕМ. feed 2257; 
STRN_wdev 2258; 
ӨТЕМ. job = 259; 
STRN_bool 2260; 
WIND.main 2256; 
(Constant declared for field windowKind) 


( enumeration literals ) 


myDocument = 8; 
( Character ) 
Return = $00; 
VAR 
myWindow : WindowPtr; 
myPeek : — WindowPeek; 
hTE : TEHandle; (The active text edit handle) 


printHdl : THPrint; (for actual printing) 


myMenus : ARRAY[1..lastMenu] OF MenuHandle; 
dragRect : Rect; 
theChar : CHAR; (Keyboard input here) 


doneFlag : BOOLEAN; 

printFlag : BOOLEAN; (user selected 'Print.' ) 
currWMode : MyWindMode; ( sets menu options ) 
myEvent : EventRecord; (Shared by all routines) 
watchHd] : CursHandle; (Тһе wait cursor) 

wdh : WindowDataHandle; ( temporary ) 

ph : THPrint; ( temporary for TPrint record ) 
spare : Ptr; (to be used by the next window) 
linebuff : Str255; 


IMPLEMENTATION 
END. 
UNIT StringFormat; 


( WHAT: 
( WHO: 


INTERFACE 


PROCEDURE SWrite (VAR s : Str255; с: CHAR); 
PROCEDURE SWriteHex (VAR s : Str255; п : LongInt; 
w : INTEGER); 
PROCEDURE SWriteInt (VAR s : Str255; п: 
w : INTEGER); 
PROCEDURE SWriteString (VAR s : Str255; s2 : Str255); 


IMPLEMENTATION 


Def inition of string formatting librery) 
Joel West, Western Software Technology] 


LongInt; 


( WHAT: Implementation of UNIT StringWrite) 

( WHO: Joel West, Western Software Technology) 

( WHEN: November 1986) 

( HOW: Formatted output to Pascal strings. Names match) 
Modula-2 InOut module. Developed to replace -) 


albeit awkwardly – use of C sprintf.) 


( As with all the Pascal equivalents, output the specified ) 
( field width or the minimum necessery number of digits, ) 
( whichever is greater.) 


( format a character ) 
PROCEDURE SWrite; ((var s : Str255;c : CHAR);) 
VAR 
i : INTEGER; 
BEGIN 
i := length(s) + 1; 
IF i « 255 THEN 
insert(c, s, i2; 
END; (% SWrite *) 


( format a number in hex  ) 
PROCEDURE SWriteHex; ((var s : Str255;n : LongInt;w : 
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INTEGER); ) 
VAR 
d, i : INTEGER; 
62 : Str255; 
BEGIN 
52 := ''; 
FOR i := 1 TO w DO 


S2 := concat(s2, ' '); 
WHILE w » 6 DO 
BEGIN 
d := BitAnd(n, $0F); 
n := BitShift(n, -4); (right shift) 
IF d « 10 THEN 
IF w « 255 THEN 
BEGIN 
delete(s2, w, 1); 
insert CCHRCORDC 8") + d), 52, w) 
END 
ELSE IF w « 255 THEN 
BEGIN 
delete(s2, w, 1); 
insert(CHRCORDC'A') - 18 + d), 52, w); 


м = и - db 
END; (while) 

SWriteString(s, $2); 
END; (* SWriteHex *) 


( format & number in decimal ) 
PROCEDURE SWriteInt; ((ver s : Str255;n : LongInt;w : 
INTEGER); ) 
VAR 


i : INTEGER; 
52 : Str255; 
BEGIN 
NumToString(n, 52); 
i := w - Length(s2); 
WHILE i > Ø DO 
BEGIN 


SWriteCs, ' ');(* Leading spaces *) 
1:=1- 


END; 
SWriteString(s, $2); 
END; (% SWriteInt *) 


( format a character string  ) 
PROCEDURE SWriteString; ((ver s : Str255; s2 : Str255);} 
BEGIN 
S := Concet(s, 52); 
END; (* SWriteString *) 
END. 
UNIT SetupMenus; 


INTERFACE 


USES 
MacPrint, MyGlobals, Windows; 


PROCEDURE SetUpMenus; 
PROCEDURE SetUpW indow; 


IMPLEMENTATION 


( These routines used only once then segment dumped ) 
PROCEDURE SetUpMenus; 
VAR 
counter : INTEGER; 
BEGIN 
FOR counter := 1 TO lastMenu DO 
nyMenus [counter] := GetMenuCcounter ); 
AddResMenu(myMenus[ 1], 'DRVR'); (desk accessories ) 
FOR counter := 1 TO lestMenu DO 
InsertMenu(myMenus[counter], 0); 
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DrawMenuBar ; 
END; (SetUpMenus) 


PROCEDURE SetUpWindow; 
VAR 


r : Rect; 
BEGIN 
dregRect := screenbits.bounds; 
dregRect.top := dragRect.top + 28; (room for menu ber) 
InsetRect(dragRect, 4, 4); (dragged rect on screen) 
doneF lag := FALSE; 
printFlag := FALSE; 
currWMode := nullMode; 


OpenAWindow; (WindowStuff routine) 
END; (SetUpWindow) 


END. 
UNIT Windows; 


INTERFACE 


8 
MacPrint, MyGlobals, DumpTPrint; 


PROCEDURE CheckW indowMode ; 
PROCEDURE CloseAW indow; 
PROCEDURE DialogueDeactivate; 
PROCEDURE DrawWindow; 
PROCEDURE MyActivate; 
PROCEDURE OpenAWindow; 


IMPLEMENTATION 
( Windows segnent ) 


(—-—-—---Updete menus based on windows------- Е) 
PROCEDURE CheckWindowMode; 
VAR 


newnode : MyWindMode; 
fileset : SET OF 1..lastFileltem; 
. item : INTEGER; 
BEGIN ( This routine sets menu items besed on window mode ) 
myPeek := WindowPeek(FrontWindow); 
IF nyPeek = NIL THEN 
newmode := NullMode ( no windows open ) 
ELSE IF myPeek* .windowKind = MyDocument THEN 
newmode := OpenMode ( document window on top ) 
ELSE 
newmode := DAMode; ( assume must be D.A. on top ) 
IF newmode <> currWMode THEN ( Must change menus ) 
BEGIN 
CASE newnode OF 
NullMode : ( No windows open ) 
fileset := [newIten, quitI tem); 
OpenMode : ( One window open and on top } 
fileset := {closeItem, stlItem, jobItem, setupItem, 
printItem, quitItem]; 
D . 


AMode : ( DA on top ) 
fileset := [closeItem, quitItem]; 
OTHERWISE 
BEGIN 


END; 
END; (CASE newmode) 
FOR item := 1 TO lestFileItem DO 
IF iten IN fileset THEN 
EnablelItem(nyMenus([f ileMenul, item) 


DisebleItem(nyMenus(f ileMenul, item); 
IF newnode = DAMode THEN 
EnebleItemC(nyMenus[editMenu], 8) 
LSE 
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DisebleItem(nyMenus[editMenu], 9); 


DrawMenuBer ; ( menu dimming must be updated ) 
currWMode := newmode; 
END; (IF newnode <> currWMode) 
END; (CheckWindowMode) 


(----------Close the front window--—-------) 
PROCEDURE CloseAWindow; 
BEGIN 


( This routine closes an app! Cor DA) window, either after) 
( о clicking go-away box ) 
( Oselecting "Close" in File menu ) 
nyPeek := WindowPeek(FrontWindow); 
IF nyPeek^ .windowKind = myDocument THEN 
BEGIN 
wdh := WindowDeteHandleCGetWRef ConCWindowPtr CmyPeek))); 
ph := wdh^^.theTHP; 
DisposHendleCHendleCph2); 
TEDisposeChTE); 
hTE := NIL; 
DisposHendleCHendleCwdh2); 
DisposeWindowCmyW indow); 
END (myDocunent window) 
ELSE ( Must be a DA ) 
CloseDeskAcc(myPeek* .windowK ind) 
END; (CloseAWindow) 


(eae Deactivate before dialog----------} 
(Deactivate the top window if we're about to put up a dialog) 
PROCEDURE DielogueDeact ivate; 
VAR 
temprect : Rect; 
BEGIN 


SetCursor Carrow); 
IF hTE € NIL THEN (for documents, only) 
TEDeact ivateChTE); 
END; (DialogueDeactivate) 


(---------Draw ә document window----------) 
( Handles window Update Event) 
е DrewWindow; 


tempport : GrefPtr; 
temprect, rectToErese : Rect; 
temppeek : WindowPeek; 
whichwindow : WindowPtr; 
temphTE : TEHandle; 
BEGIN 
whichwindow := WindowPtr(mgEvent . message); 
Beg inUpdateCwhichwindow); 
GetPort( tempport ); 
SetPort(whichwindow); 
temppeek := WindowPeek(Cwhichwindow); 
IF temppeek^ .windowKind = myDocument THEN 
EGIN 


temprect := whichwindow^ .Portrect; 

wdh := WindowDeteHaendleCGetWRef ConCwhichwindow2); 

temphTE := wdh^*^.theTE; 

SetRect(temprect, -32767, -32767, 32767, 32767); 

ClipRect( temprect); 

{erases the window past the end of text, if any} 

WITH temphTE** DO 

IF nLines < CviewRect bottom - viewRect.top + 
lineHeight) DIV lineHeight THEN 

BEGIN 


rectToErese := viewRect; 
rectToErese.top := (nLines) * lineHeight; 
EraseRect(rectToErase 2 
END; (nLines) 
TEUpdateCwhichwindow^.visRgn^^.rgnBBox, temphTE) 
END; (myDocument stuff) 
SetPortCtempport); 
EndUpdateCwh ichwindow) 
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END; (DrewWindow) PROCEDURE DumpPrInfo (msg : Str255; prinf : TPrInfo); 
PROCEDURE DumpPrXInfo (msg : Str255; prxi : TPrXInfo); 


(-------------Handle (deactivate events----------- ) PROCEDURE DumpPrSt! (msg : 517255; ps : ТРг5+1); 
PROCEDURE MyActivate; PROCEDURE DumpPrJob (msg : Str255; pj : TPrJob); 
PROCEDURE DumpPrintX (msg : Str255; tpp : TPPrint); 
BEGIN (This activates or deactivates current selection) PROCEDURE DumpPrint (msg : Str255; hand : THPrint); 
myWindow := WindowPtr(myEvent .message ); 
myPeek := WindowPeek(myWindow); IMPLEMENTATION 
IF nyPeek^ .windowKind = myDocument THEN 
BEGIN ( document window ) ( ----------- Add a line to document-------------} 
wdh := WindowDetaHendleCGetWRefConCmyW indow)); PROCEDURE PrintLine; 
hTE := wdh^^.theTE; VAR 
IF ODD(mnyEvent .modif iers) THEN p : Ptr; 
( BitAndlmyEvent.modif iers,ectiveFlag»8 ) c : SignedByte; 
TEActivateChTE) (this window is now top most) BEGIN (this adds the line to end of the display) 
ELSE (this window is no longer top most) p := @linebuff; 
BEGIN TEInsert(PointerCORD4(p) + 1), LengthClinebuff), hTE); 
TEDeactivateChTE); c := Return; 
hTE := NIL (а TextEdit window is no longer on top) TEInsert(@c, 1, hTE); ( add CR ) 
END; WITH hTE^* DO ( Check if beyond bottom of page ) 
END; IF ClineHeight * nLines) > (viewRect.bottom - 
END; (MyActivate) viewRect.top) THEN 
TEScrol1C90, -hTE^^.lineHeight, ҺТЕ); ( scrol] 
(-------------Create а new document window------- ) up one line ) 
PROCEDURE OpenAW indow; linebuff := ''; 
END; (PrintLine) 
VAR 
r : Rect; (------------Formatting utilities---------------- ) 


PROCEDURE PrintTab; 
BEGIN (A window is created here) VAR 


col, nexttab : INTEGER; 


myWindow := GetNewWindowCWIND.main, NIL, Pointer(-1)); BEGIN ( add spaces to next multiple of 8 ) 
wdh := WindowDetaHandleCNewHandleCSIZEOFCWindowData))); col := Length(linebuff); 
SetWRef ConCmyW indow, ORDCwdh)); nextteb := col - INTEGER(BitAnd(col, 72) + 8; 

( stash pointer to TEHandle in window ) WHILE col « nextteb DO 

BEGIN 

SetPort(myW indow); col := col + 1; 
myPeek := WindowPeek(myWindow); IF col « 255 THEN 
TextFontCmyStdFont); insertC' ', linebuff, col); 
TextSize(nyStdSize); END; 
DrewChar(C' '); END; 
SetFontLockCTRUE); PROCEDURE PrintHex; (Cn : LONGINT; w : INTEGER );) 
myPeek* .windowKind := myDocument; (id type of window) BEGIN 


SWr iteHexClinebuff, n, ж); ( actual width ) 


r := myWindow^ .Portrect; END; 
InsetRect(r, 8, 4); PROCEDURE PrintInt; (Cn : LONGINT);} 
hTE := TENewCr, r); BEGIN 
wdh*^.theTE := hTE; SWriteIntClinebuff, n, 0); ( minimum width ) 
hTE^^.destRect := hTE^^.viewRect; END; 
hTE^^ .crOnly := -1; ( no automatic CR ) 
PROCEDURE PrintString; ((s : Str255);)} 
PrOpen; BEGIN 
ph := THPrintCNewHandleCSIZEOFCTPr int 222; SWriteStringClinebuff, 9); 
PrintDefaultCph); END; 
wdh^^.theTHP := ph; PROCEDURE PrintStrNum; {Cs : Str255; п: LONGINT );) 
DumpPrintC'After PrintDefeultC.)', ph); BEGIN ( format a string and integer ) 
PrClose; PrintTeb; 
SWriteString(linebuff, s); 
END; (OpenAWindow) SWriteIntClinebuff, n, Ø); ( minimum width ) 
END. END; 
UNIT DumpTPrint; PROCEDURE PrintStrHex; (Cs : Str255;n: LONGINT;w : INTEGER);} 
INTERFACE BEGIN ( format а string and hex ) 
USES PrintTeb; 
MacPrint, MyGlobals, StringFormat; SWriteString(linebuff, s); 
PROCEDURE PrintLine; SWriteHexClinebuff, п, w); 
PROCEDURE PrintTab; END; | 
PROCEDURE PrintHex (n : LONGINT; w : INTEGER); 12227525555 Format enumeration ------------ ) 
PROCEDURE PrintInt (n : LONGINT); PROCEDURE DumpEnum; ((msg : Str255; val, resid : INTEGER);} 
PROCEDURE PrintString (s : Str255); VAR 
PROCEDURE PrintStrNum (s : Str255; n : LONGINT); S : 517255; 
PROCEDURE PrintStrHex (s : 517255; п: LONGINT; rh : Handle; 
w : INTEGER); limitp : WordPtr; 
PROCEDURE DumpEnum (msg : Str255; val, resid : INTEGER); err : boolean; 
PROCEDURE DumpRect (msg : Str255; r : Rect); BEGIN 
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err :* TRUE; 
PrintTab; 
Pr intStr ing(msg); 
rh := GetResourceC'STR*', resid); 
IF (rh © NIL) THEN 
format ) 
BEGIN 
limitp := WordPtr(rh*); ( number of strings } 
IF (vel >= 0) AND (val < limitp*) THEN 
BEGIN ( in range def ined ) 
GetIndString(s, resid, val + 1), 
PrintString(s); 
err := FALSE; 


END 
END; 
IF err THEN 
PrintIntCval); 
END; 


( no string, show the integer ) 


( --------------- Format Rect ------------- ) 
PROCEDURE DumpRect; ((msg : Str255; r : Rect);} 
BEGIN 


PrintStr ing(msg); 
PrintStringC': (9; 
Printint(r. top); 
PrintStringC', '); 
PrintInt(r. left); 
PrintStringC', '2; 
PrintIntCr.bottom); 
PrintStringC', '2; 
PrintIntCr.right2; 
PrintStringC')'2; 
PrintL ine; 
END; 
(:45----1-21525- Format TPrInfo ----------- ) 
PROCEDURE DumpPrInfo; ((msg : Str255; prinf : TPrInfo);) 
BEGIN 


PrintString(msg); 
PrintStrNumC' iDev: ', prinf.iDev); 
PrintStrNumC'iVRes: ', prinf.iVRes); 
PrintStrNumC'iHRes: ', prinf. iHRes); 
PrintL ine; 
DumpRect(C'rPage', prinf .rPage); 
END; 
(------------- Format TPrXInfo ------------- ) 
PROCEDURE DumpPrXInfo; ((msg : Str255; prxi : TPrXInfo2;) 
BEGIN 
PrintString(msg); | 
PrintStrNumC' iRowBytes: ', prxi. iRowBytes); 
PrintStrNunC' iBaendH: ', ргхі. iBandV); 
PrintStrNunC' iBendV: ', ргхі. iBandH); 
PrintLine; 
PrintStrNunC' iDevBytes: ', ргхі. iDevBytes); 
PrintStrNumC' iBands: ', ргхі. iBands); 
Ргіп ine; 
PrintStrNumC'bPatScale: ', prxi.bPatScale); 
PrintStrNunC'bUlThick: ', prxi.bUTThick); 
PrintStrNunC'bUlOffset: ', prxi.bUTOffset); 
PrintStrNumC'bUlShadow: ', prxi.bUlShadow); 
PrintL ine; 
DumpEnumC'scen: ', ORDCprxi.scan), STRN_scan); 
PrintStrNumC'bXInfoX: ', prxi.bXInfox); 
PrintLine; 
END; 
( ------------ Format ТРг511 ------------ ) 
ii коз DumpPrSt!; (€ msg : Str255;ps : TPrSt12;) 
BEG 


PrintStr ing(msg); 

PrintStrHexC'wDev: $', ps.wDev, 4); 
DunpEnumC'C', BitShiftC(ps.wDev, -8), STRN_wdev); 
PrintString(')'); 

PrintLine; 

PrintStrNum('iPageV: ', ps. iPageV); 
PrintStrNum('iPageH: ', ps. iPageH); 
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( if we screwed up, don't try to 


PrintStrNumC'bPort: ', ps.bPort); 
DumpEnum( ' f eed: ‚ ORD(ps. feed), STRN. feed); 
PrintLine; 
END; 
(=== Format TPrJob ------------- } 
PROCEDURE DumpPrJob; ((msg : Str255; pj : TPrJob2;) 
BEGIN 
PrintString(msg); 
PrintStrNumC' iFstPage: ', pj. iFstPage); 
PrintStrNunC' iLstPage: ', pj. iLstPage2; 
PrintStrNumnC' iCopies: ', pj. iCopies); 
DumpEnumC'bJUDocLoop: ', ORD(pj.bUDocLoop), STRN. job); 
PrintLine; 
DumpEnunC'fFromUsr: ', ORDCpj.fFromUsr), STRN_bool); 
PrintStrHexC'pIdleProc: ', ORD4Cpj.pIdleProc2, 8); 
PrintStrHexC'pFileNeme ', ORD4(pj.pFileName), 8); 
PrintLine; 
PrintStrNumC' iFileVol: ', pj. iFileVol); 
PrintStrNumC'pFileVers: ', pj.bFileVers); 
PrintStrNumC'bJobX: ', pj.bJobX2; 
PrintLine; 
END; 
( ------------ Format printX Array ---------- ) 
MR DumpPrintX; (С msg : Str255;tpp : TPPrin — );) 


i, mex : INTEGER; 

BEGIN ( Outputs non-zero values, if any) 
max := 9; 
FOR i := 1 TO 19 00 

IF Ctpp^.printXLi] © 0) THEN 

max := d; ( ignore trailing zeroes ) 

IF (тах > 0) THEN 

BEGIN 


PrintString(msg); 
FOR i := 1 TO max DO 
BEGIN 
PrintStrNunC' [' ,. 1); 
PrintStringC']: '); 
PrintHexCtpp^ .printX[i], 4); 
IF СССі MOD 4) = Ø) OR Ci = пах)) THEN 
РА PrintLine; ( every 4th ог lest one ) 


END 
END; 
( ------------- Format TPrint ---------- --) 
ИВЕ DumpPrint; ((msg : Str255;hend : THPrint);} 


tpp : TPPrint; 
i : INTEGER; 

BEGIN 
HLockCHendleChand)); 
{рр := hend^; ( pointer to a TPrint ) 
PrintLine; 
PrintStr ing(msg); 
PrintLine; 
FOR i := 1 TO Length(msg) 00 

PrintStringC'-' 5; 

PrintLine; 
PrintStringC' iPrVersion: '2; 
PrintIntCtpp^ . iPrVersion); 
PrintLine; 
DunpPrInfoC'prInfo', tpp*.prinfo); 
DumpRect('rPeper', tpp*.rPaper); 
DumpPrStiC'prStl', tpp*.prst1); 
DumpPrInfoC'prInfoPT', tpp^.prInfoPT); 
DunpPrXInfoC'prXInfo', tpp^.prXInfo); 
DumpPrJobC'prJob', tpp^.prJob); 
DumpPrintXC'printX', tpp2; 
PrintString( == ea 


ni Vis vun ee enh qm ese tui imis (miS is Ой el es Qui Gui quo Sid Qul Qui le Ses Gua uum nta ee ede es ese et So аш аралы Ё ) . 
PrintLine; 


HUnLock (HandleChand2); 
END; (DumpPrint) 
END. 
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UNIT Printing; 
INTERFACE 


USES 
MacPrint, MyGlobals, Windows; 


PROCEDURE DoPr int ing; 


IMPLEMENTATION 
(--------- Print out а document window-----------} 
PROCEDURE DoPrinting; 
CONST 
bottommargin = 20; ( pixel margin inset from rPage ) 
leftmargin = 30; 


rightmargin = 10; 
topmargin = 36; 


VAR 
txth : Handle; 
printTE : TEHandle; 
MyPPort : TPPrPort; 
dlogptr : DialogPtr; 
txtptr : Ptr; 
linesperpage, height, firstoffset: INTEGER; 
lastoffset, leftpos, toppos: INTEGER; 
fstpos, lineno, lastline, linecount: INTEGER; 
pageno, firstpage, lastpage, numpages: INTEGER; 
copyno, numpasses, dummyitem, errno : INTEGER; 
pagerect : Rect; 
currstr, laststr, heading : Str255; 
strhð, strhi, hdgstrh : StringHandle; 
status : TPrStetus; 
info : FontInfo; 
lestonpage : ARRAY[0..99] OF INTEGER; 
each page ) 


( NOTES ) 


( last line # on 


( This section images each page, using QuickDraw via ) 

TextEdit. А few special cases:) 

1. For spooled output CIW only), image and then print) 

2. For IW draft mode, must send multiple copies ourself} 
This has been rewritten from skeleton code, for a number) 
of key reasons:) 

1. A location is found for a line, then DrawText is) 
used to drew the line. This requires setting the font) 
directly in the printing GrafPort. The skeleton used ) 
TextBox for each page; TextBox uses EreseRect which, ) 
according to Technical Note #72, is very slow on the ) 

LaserWriter.) 

2. We use crOnly, so only returns аге used for line ) 
breaks. Thus, we don't need a new TECalText for the) 
printing destRect, but instead use the TextEdit ) 
lineStarts established for display purposes.) 

3. This routine figures out the actual pages selected ) 
and then prints only those pages. (The values of ) 
prJob.iFstPage апа iLstPege need to be fudged to ) 
do this.2) 

. Put & heading on each page, showing page number.) 

. Put up en Alert if a printing error is encountered.) 
Not strictly necessary, since the most commonly found) 
"errors" ere user- specified eborts that should be ) 

ignored.) 


ы aoe оғ ғғ ғғ ғ” Cam ы ғо, ғ бы лт, ұға ы, aaa T ғо, б бы об сб, а, ыы бы, ұғ” 
oO >» 


BEGIN 

printFlag := FALSE; 

DialogueDeactivate; 

IF PrJobDialog(printHd]) THEN 
BEGIN 


( so we don't print again ) 
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SetCursor(watchHdl^^); ( Put up progress dialog ) 

strhü := GetString(STR prepare); 

PeremText(strh^^, '', '', ''), 

dlogptr := GetNewDialog(DLOG_printing, NIL, Pointer(- 12); 
DrewDialog(dlogptr); 

printTE := hTE; 

( Calculate # of pages & line numbers for each page ) 
ин реи printHdl^^.PrInfo 00 


txth := hText; 
height := lineHeight; 
linecount := nLines; 
linesperpage := (rPage.bottom - rPage.top - bottom- 
margin - topmargin) DIV height; 
pagerect := rPage; ( top margin allows for heading } 
pagerect.left := pagerect.left + leftmargin; 
pagerect.right := pagerect.right - rightmargin; 
pagerect bottom := pagerect.top + topmargin + Cline- 
Ѕреграде * height); 
fstpos := pagerect.top + topmargin + fontAscent; 
( base line of first line of text in document } 
END; (WITH) 
lastonpage[9] := Ø; 
pageno := 1; 
lineno := 0; 
WHILE lineno ‹ linecount DO  ( until out of pages ) 
BEGIN 
lineno := lineno + linesperpage; 
IF lineno < linecount THEN — ( all but last page ) 
lestonpage[pageno]l := lineno - 1 ( last line ) 
E ( last page ) 
lastonpage[pageno] := linecount - 1; 
( lines numbered 8..n ) 
pageno := pageno + 1; 
END; (WHILE lineno) 
numpages := pageno - 1; 


( We could skip page calculations, but then we would image ) 
(811 pages and Print Manager would print only those) 

( selected. Obviously this is inefficient for ) 

large documents. Instead, fool Print Manager into) 
thinking enough pages are selected end then do ) 

actual printing starting et the selected page. ) 

This MUST be done before PrOpenDoc. ) 


POR FPR qum, qium, 


WITH printHdl^^.PrJob DO 
BEGIN 


firstpage := iFstPage; ( page numbers requested ) 
IF firstpage « 1 THEN 
firstpage := 1; 
lestpage := iLstPege; 
IF lastpage > numpages THEN 
lastpage := numpages; ( limit to available pages } 
numpages := lastpage - firstpage + 1; { actual length } 
iFstPage := 1; ( fool print manager } 
iLstPage := numpages; { reset by next PrJobDialog ) 


( Manual handling of multiple copies for draft mode only) 
( ImageWriter spooling handles this directly; the ) 

( LaserWriter PruobDialog always sets iCopies := 1 end ) 
( hides the actual number of copies from us ) 

( Also set up appropriate progress message ) 


IF bJDocLoop = bSpoolLoop THEN 
BEGIN 


numpasses := 1; ( only one pass through ) 
strhð := GetStringCSTR.spooling2; ("Now spool.. ") 


numpasses := iCopies; ( draft, multiple passes ) 
strhd := GetString(STR_pr inting); ("Now print.. ") 


END; 
END; (WITH) 
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strhi := GetString(STR. of); ("of") 
hdgstrh := GetString(STR_pagehead); ( "Page ") 


Now do actual printing Cor imaging, for spool mode ) 
Get & drewing port: TPrint should be frozen by now ) 


end once per page. Show dialog progress in terms of ) 


( 
t Go through it once for every copy Cif necessary) ) 
( 


pages to be printed ) 


MyPPort := PrOpenDoc(printHdl, NIL, NIL); 
NumToString(numpages, laststr);  ( * of pages to print ) 
eae := 1 TO numpasses 00 

BEGIN 


MoveHHiCtxth); 
HLockCtxth); 
txtptr := txth^; 


FOR pageno := firstpage TO lastpage DO 
BEGIN ( Image each page; does printing draft mode } 
IF PrError = noErr THEN 
BEGIN 
NumToStr ing(pageno - firstpage + 1, currstr); 
(relative page # 
PeremText(strh^^, currstr, strh1^^, laststr); 
DrawDialog(dlogptr); ( update the status ) 
PrOpenPage(MyPPort, NIL); ( changes GrafPort ) 


( First put a heading on the page. Since MoveTo location ) 
( for drawing text is the base line, need ascent to } 
(position heading within pagerect ) 


Tex tFont CmyHdgFont); 
TextSizeCmyHdgSize); 
GetFontInfoCinfo); { need ascent height } 
NunToStr ingtpageno, heading); ( abs. page 8 ) 
heading := ConcatChdgstrh^^, heading); (Page 1) 
WITH pagerect DO 

BEGIN 

leftpos := left + ((right - left - 


StringWidthCheading)) DIV 2); ( center } 


MoveToCleftpos, top + info.ascent); (base line ) 
DrewStringC(heading); ( print page heading ) 

( Now print actual document for this page ) 
leftpos := left; (Тегі margin for text ) 
toppos {= fstpos; ( base line for ist line ) 


TextFont(printTE^*. txFont); 


( set for display ) 


TextSizeCpr intTE**. txSize); 
lineno := lastonpage [pageno - 11; ( line of TERec ) 
firstoffset := printTE^^.lineStarts(1ineno]; 
lestline := lastonpage[pageno]; 
( Draw each line in TERec, except CR at line end. ) 
WHILE lineno <= lastline DO 
BEGIN 
MoveToCleftpos, toppos); 
lineno := lineno + 1; 
IF lineno >= linecount THEN 

lestoffset := printTE**.teLength (last) 
ELSE 

lestoffset := printTE^^.lineStarts(lineno] - 1; 
ÜrewTextCtxtptr, firstoffset, lastoffset - first- 


offset); 


toppos := toppos * height; 
firstoffset := lestoffset + 1; 
END; (each line) 
PrClosePage(MyPPort); ( done with this page ) 
END; (If no Prerror) 
END; (for each page) 


HUnLock( txth2; 


END; (each copy) 

PrCloseDoc(MyPPor t); 

( If spooled, the file isimaged and need to print it ) 

IF C(printHdl^^.prJob.BJUDocLoop = BSpoolLoop) AND (PrError 
z noErr) THEN 
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BEGIN 
strhü : = GetString(STR-prspoo!2; ( "Now ѕроо1.." ) 
ParenText(strh£"^, ecu EP 7 
DrawDialog(dlogptr); 
PrPicFileCprintHdl, NIL, NIL, NIL, status); 
END; 
( Drop the advice dialog ) 
DisposDialog(dlogptr); 
SetCursor Carrow); 
errno := PrError; 
IF Cerrno € noErr) AND Cerrno € iPrAbort) AND Cerrno o 
ilOAbort) THEN ( indicate a printing error, unless. ) 
( user hit command-period ) 
( user cancel on "not responding" alert ) 
BEGIN 
NumToStr ingCerrno, currstr); ( error number ) 
PeremTextCcurrstr, '', '' 
dummyitem := Rc ter Лр nian NIL); 
END; 
END (IF PrJobDialog) 
ELSE ( Cancel in PrJobDlog ) 
PrSetErrorCiPrAbort); 
END; (DoPrinting) 


* PrintTest.R 

* Copyright 9 1986 by 

* Joel West 

х Western Software Technology 
x for MacTutor 


PrintTest.RSRC 
229729727 


Type JWES = STR 

PrintTest,@ 

PrintTest by Joel West, Version 1.0: 38-Nov-86 
Type FREF 

PrintTestApp!, 128 

APPL 0 


Type BNDL 
PrintTest, 128 
JWES 0 


& ------ Switcher events --------- 
Туре SIZE = GNRL 

,-1 
4 


16384 вес bit 14 for resume 
.L 
98304 ;; 128K preferred 
L 
98304 3, 128K minimum 
Ro essere emm Alerts ---------- 
TYPE ALRT 
,256 
40 131 140 381 
256 
4444 
TYPE ALRT 
,251 
40 131 140 381 
251 
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к --------- Dialogs -------------- 


type DLOG 

,258 
Print Messages 
100 120 200 392 
Visible NoGoAway 
1 
0 
258 


type DITL 
,258 
1 


StatText Disabled 

15 40 85 232 

^9 1°2°3..\OD\OD ++ 
To cancel, type \11-. 


type DITL 
,256 


BtnIten 
60 105 80 175 
OK 


StatText Disabled 
10 64 42 264 
“0 


{уре DITL 
,251 


BtnItem 
T0 60 90 130 
OK 


StetText Disabled 


10 64 58 172 
Printing error, ID = “0. 


Type MENU 
* the desk acc menu 
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1 
\14 | ;;арр1е menu 
About PrintTest.. 
(- 


* the file menu 


File 


PrSt1Dialog.. /S 
PrJobDialog.. /J 
(- 


Page Setup.. 
Print.. /P 
(- 
Quit /Q 
* the edit menu 
‚3 
Edit 
(Undo /Z 
(- 
Cut /X 
Copy /C 
Paste /V 
Clear 
TYPE WINO 
,256 
PrintTest 
46 8 327 507 
Visible GoAway 
4 
0 
ТҮРЕ STR 


‚256 
PrintTest by Joel West\@D ++ 
Version 1.0: 30-Nov-86 


TYPE STR 
,251 


Pege 


TYPE STR 
‚300 


Prepering document for printing 


TYPE STR 
‚301 
Now printing раде 


TYPE STR 
, 302 
Now spooling pege 


TYPE STR 
‚ 303 
of 


TYPE STR 

‚304 
Now printing ++ 
Spooled document 


Туре STR! 
,256 


scanTB 
scanBT 
scanLR 
ScenRL 


Type STR# 
7 


9 


feeCut 
feedFanfold 
feedMechCut 
feedO ther 


Type STR! 
8 


д 


screen 
Imagewr i ter 
Daisywriter 
LaserWr i ter 


Туре STR" 
,259 


2 
bDref tLoop 
bSpoolLoop 


Type STRE 
,260 


false 
true 


TYPE ICN® = GNRL 
PrintTestApp1, 128 
H 


0000 0000 0000 0000 
IFFF FFFO 1000 0010 
12A9 0010 1000 0010 
1360 0010 1240 0010 
1240 Е010 1308 Е010 
1360 0010 1000 0010 
1000 0010 1000 0010 
SFFF FF91 5000 0052 
30Т7Ғ F83C 0800 0010 
O87F Ғ810 0800 0010 
08ТЕ Ғ810 0800 0010 
0800 0010 OFFF ҒҒҒ0 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
0000 0000 0000 0000 
* mask 

FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 
FFFF FFFF FFFF FFFF 


^ — 
. . 


бм 


catus 


255 


Pascal Procedures 
Reading Paint Files 


Paint files have become generic on the Macintosh as a way of 
transferring bit mapped type graphics information between 
applications. Several commercial programs have come out that 
can read and write MacPaint file formats, making support of this 
type of Macintosh object an important design consideration. 
FullPaint by Ann Arbor Softworks is one of the most popular 
MacPaint alternatives because it is the most faithful to the 
original design in simplicity and function, yet improves on the 
obvious limitations of MacPaint without introducing any new 
wrinkles or problems to get in the way. Thunderscan by Thunder- 
ware & Andy Hertzfeld opens, reads and writes paint files with 
the added feature that you can use Andy's wonderful "moving 
window" scroller to select any part or all of a paint drawing for 
alteration. As such, it is a useful paint editor. Paint Cutter by 
Silicon Beach Software has some important features including 
the ability to make large selections and rotate large selections of 
a paint diagram. This is especially useful in combination with 
Thunderscan drawings that must be rotated. SuperPaint also by 
Silicon Beach Software offers a "MacDraw-MacPaint" combo 
that can be very powerful in addition to reading and writing paint 
files. As aresult of all this developer support for paint documents, 
the ability to read and display a paint type document could be an 
important design element in your application. 

As figure 1 shows, our program this month illustrates how to 

TYPE CREATOR 


PNTG | мент 


Data Fork Format 


Header 
212 bytes 


Bit Map 
576 pixels 
by 
720 pixels 
(compressed) 


Resource Fork Format 


Fig. 2 Format of Paint File Data Fork 
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PaintReader 


Gary Palmer 
University of Nevada 
MacTutor Vol. 3 No. 5 


Test Case No. 1 


Fig. 1 Our Paint Reader Program 


open and read a MacPaint type document, displaying it in a 
window at 3/8's of it'S normal size. Add this to a paint type 
program and you can expand to editing and any number of other 
quickdraw functions. 

MacPaint documents are described in technical note number 
86 released last August, and according to the note header, the note 
was written by Bill Atkinson in 1983! Figure 2 summarizes the 
format of the MacPaint document. 

The beginning of a MacPaint file is a 512 byte header block, 
which contains the version number, pattern array, and empty 


space. The header matches the following record example: 
MPHeader = RECORD 


version: X LongInt; 
PatArray: Array [1..39] of Pattern; 
Future: PACKED ARRAY [1..204] OF SignedByte; 

END; 

Typically, the version number is zero, in which case the 
patterns are ignored and MacPaint uses the default patterns 
instead. Applications can ignore the header by skipping it when 
reading a document or by writing out 512 bytes of zero when 
writing a paint document. (Recall that a Pattern is 8 bytes so the 
PatArray is 38*8 = 304 bytes.) 

Paint documents are a screen dump at 72 dots per inch, of the 
bit map, which represents a 576 pixel wide (72 bytes times 8 bits 
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Main 
Program | 


Fig. 3 Program Flowchart 


per byte) by 720 pixel tall array, thus covering an 8 by 10 inch 
document. Each line of 72 bytes, representing 576 pixels is 
shoved through the trap PackBits to output a single pixel line, 
until all 720 lines have been packed. Therefore, the maximum 
size of an unpacked bit map is 720 lines by 72 bytes per line or 
51,840 bytes. With the PackBits routine, this compresses down 
to about 10,000 bytes normally. 
Program Details 

To read the file, we call the standard file routine to get a file 
name and reference number, then call FSOpen to open the file. 
We can skip the 512 byte header by positioning the file marker 
past the first 512 bytes with SetFPos. We determine the size of the 
file by calling GetEOF, and then subtracting the 512 header bytes 
to determine the number of bytes making up the bit map, which 
is what we want to read and display. We then use FSRead to read 
in the bit map into the buffer and close the file. (See figure 3 above 
for flowchart.) 

To prepare the bit map for display, we have to unpack it. This 
can be done by calling UnPackBits in a loop, unpacking 72 bytes 
at a time until all the lines of the document (720) are done. The 
nice thing about MacPaint is that it doesn't try to do anything 
fancy with variable size files. All files have the same 720 lines to 
unpack. Sometimes simplicity is a great virtue! In our program, 
we just divide the bit map in two and call UnPackBits twice. 

Once the bit map is unpacked, we can copy the bit map to an 
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off-screen bit map we have allocated, and then to our window to 
display the document in a destination rectangle. By making the 
destination rectangle 3/8's the size of the document, we can 
nicely display the entire drawing at a reduced size. In our 
program, we have scaled everything to ScreenBits.bounds, so on 
a larger display, a bigger proportional picture would also be 
displayed. This is a good habit to get into in preparation for 
Macintosh II. 

Our main program is fairly simple. We perform the standard 
init stuff and open a window. Then we begin our display loop 
where we continue to call standard file until the user clicks 
cancel. This is done by calling our procedure GetPaintImage, 
which in turn calls standard file, and then attempts to open the file 
and unpack the bit map, followed by DisplayPaintFile, which 
copies the off-screen bitmap to our window. À simple event loop 
is used to allow acmd-shift-3 to capture the window contents and 
save it to disk to help write this article! The real work is in our 
paint file manager unit, where the actual reading and displaying 
of the file takes place. 

Standard File Dialog 

Figure 4 shows our standard file dialog from which we get the 
name of the file. We call it with an allowed file type of PNTG so 
that we get all MacPaint type files. The standard file dialog fills 
in a Reply record from which we can extract the file name and 
reference number for the FSOpen call. After opening the file we 
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€x palmer paint files pas 


СО LSP source 

D test case Fullpaint 
О test case paint 

D test case scanner 


O TML source 


Fig. 4 Calling Standard File 


call our ReadPaintFile routine to read in the packed bit map and 
return to us a pointer to the bit map. Using the pointer, we call 
UnpackBits twice to unpack and copy the bit map to our off- 
screen bit map from which we will copy the image to the window, 
as shown in figure 3. 
Debugging Aid 

A useful feature when dealing with the file manager is our 
doMessage procedure. This little routine takes four string argu- 
ments and stuffs them into the low memory globals with Par- 
amText trap. А simple dialog is displayed that reads the four low 
memory parameters and displays them in the dialog box. This is 
useful for a quick and dirty output device, both for the user, and 


Reading Paint type... 
Bytes - header -17920 


Cor) 


Fig. 5 Paint file has even bytes 


Logical EOF Odd 
Bytes - header = 17541 
Not a MacPaint File. 


Fig. 6 Other files may have odd bytes 


fordebugging. Sinceevery file manager call returns an error code 
that must be checked, it can be a real pain while you are writing 
and testing code, to deal with a formal exception handler proce- 
dure. Our little dialog box lets you know what happened and 
where and by using NumToString, can be an easy way to find out 
the values of parameters in a hurry. Whenever you need some 
info, just stick in a doMessage() line in your code. Of course, this 
violates the resource manager thinking of Apple by putting 
human readable text in your program rather than in your resource 
fork! But, when you are done with development, a simple search 
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on doMessage would find all the strings which could then be 
transferred to a string resource for the final product. 

Each time we geta file, our doMessage proc displays a dialog 
box showing how many bytes there are in the packed bit map. It 
also shows if the number of bytes is odd. MacPaint files will 
always return even, so the dialog in figure 5 is shown. But 
sometimes another program will return an odd number of bytes, 
in which case, the dialog in figure 6 is displayed. Our program 
will attempt to read any paint type file, and other error checking 
traps will catch any problem and return the user to the desktop. 

Combining this program with the C column this month and 
adding in Joel West's article on printing a few months back, you 
have the making of the next FullPaint application! 


PROGRAM ReadPaint; 
( Reeds paint files and displays them in 3/8 normal size in ) 
( center of large window. After reading а file, press ) 
( the mouse button to read another file. Choosing cancel ) 
( in the dialog box quits the program. ) 
( Lightspeed Pascal version, but very generic! ) 
USES 
PaintFileMgr; 
VAR 


theWindow : WindowPtr; 
theWindowRec : WindowRecord; 
WindowRect : Rect; 
MeskEvents : Integer; 
theImagePtr : Ptr; 
DoIt : boolean; 
Event : eventrecord; 
( procedures start here ) 
PROCEDURE crash; 
BEGIN 
ExitToShe11; 


END; 
PROCEDURE StandardInit; 
BEGIN 
InitGref CéthePort); 
InitFonts; 
MaskEvents := EveryEvent - keyUpMask; 
FlushEvents(MaskEvents, 0); 


Ini tWindows; 
Ini tMenus; 
TEInit; 
Ini tDialogs(@crash); 
InitCursor; 
PenNormal; 
END; (StendardInit) 
PROCEDURE OpenWindow; 
CONST 
mBarHeightGlobal = $ВАА; 
VAR 
screen : rect; 
mBarHeight : Integer; 
MemoryPtr : ^Integer; 
BEGIN 


MemoryPtr := pointer(mBarHeightGlobal ); 
mBarHeight := MemoryPtr^; 
screen := screenBits.bounds; 


SetRect(WindowRect, screen.left + 4, screen.top + mBar- 
Height + 28, screen.right - 4, screen.bottom - 4); 
theWindow := NewWindow(@theWindowRec, WindowRect, PeintFile', 


True, 0, Pointer(-1), False, 0); 
SetPortCtheWindow); 
END; 
( main progrem ) 
EGIN 
MexApplZone; 


MoreMasters; 
MoreMasters; 
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StandardInit; 

OpenWindow; 

REPEAT (on theImagePtr) 
GetPaintImageCtheImagePtr); 
DisplayPaintF ileCtheImagePtr); 

IF theImagePtr <> NIL THEN 
BEGIN 
DisposPtr(CtheImagePtr); 
REPEAT (on button ) 
systemtesk; 
DoIt := GetNextEventCKeyDownMask, Event); 
IF DoIt THEN 
CASE Event.what ОҒ 
KeyDown, Autokey : 
BEGIN 
Sysbeep(5); 


OTHERWISE 
BEGIN 
END; 
END; 
UNTIL button; 


UNTIL theImagePtr = NIL; 


( Gary B. Palmer. Public domain. October 25, 1986. 
Author reserves right to use in own programs. 


END. 
( ) 
oe Unit 
( Procedures for opening and displaying Paint files with } 
( high level routines from Toolbox file manager. ) 
( might not work in a 128K Mac, but could probably be made) 
( to work by reading and unpacking the file in smaller — ) 
( chunks. ) 
(AUTHOR ) 
) 
) 
) 


UNIT PaintFileMgr; 
INTERFACE 


PROCEDURE GetPaintImage (VAR ImagePtr : Ptr); 
PROCEDURE DisplayPaintFile CImagePtr : Ptr); 
IMPLEMENTATION 
(e Internal routines -------- ) 
PROCEDURE doMessage Стеѕ0 : str255; 
mes] : str255; 
mes2 : str255; 
mes3 : 517255); 
CONST 
MessageDialog = 258; 
VAR 


dialogP : DialogPtr; 
item : integer; 
dlogRect : rect; 


ParamText(mes®, mesi, mes2, mes3); 
SetRect(dlogRect, 100, 100, 400, 200); 
dialogP := GetNewDialog(MessageDialog, NIL, pointer(-1)); 
IF dialogP = NIL THEN 
BEGIN 
SysBeep(5); 
ExitToShel1; 
END; 
initCursor ; 
ModalDialog(NIL, item); 
DisposDialogCdialogP); 
END; 


PROCEDURE SFGetPaint (VAR theReply : SFReply); 
CONST 

SFPutLeft = 100; 

SFPutTop = 100; 
VAR 
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SFPutPt : Point; 
PNTG_list : SFTypeList; 
BEGIN 
PNTG_list(@] := 'PNTG'; 
SetPtCSFPutPt, SFPutLeft, SFPutTop); 
SFGetFileCSFPutPt, '', NIL, 1, PNTG list, NIL, theReply); 


END; (SFGetPaint) 
PROCEDURE CloseOldFile CrefNum : Integer; 
vRefNum : Integer); 
VAR 
err : 05Егг; 
BEGIN 


err := FSClose(Cref Num); 
IF err © noErr THEN 
BEGIN 
doMessageC'FSClose error', 'CloseOldFile routine’, 
‘Could not close file ', ''); 
END; 
err := FlushVol(NIL, vRefNum); 
IF err © noErr THEN 
BEGIN 
doMessageC'FlushVol error’, 'CloseOldFile routine’, 
‘Could not Flush volume ', ‘'); 


END; 
END; (CloseO1dF ile) 
PROCEDURE ReadPaintFile CrefNum : Integer; 
VAR PackedBitsPtr : Ptr); 
LABEL 


1; 
VAR 
bytes : LongInt; 
stri: str255; 
err : OSErr; 
BEGIN 
PackedBitsPtr := NIL; 
err := GetEOF(refNum, bytes); (FIND LOGICAL END OF FILE) 
IF err © noErr THEN 
BEGIN 
doMessage('GetEOF error’, ‘ReadPaintFile routine’, 
‘Could not find file end', ''); 
END; 
bytes := bytes - 512; 
IF odd(bytes?) THEN 
BEGIN 
NumToString(bytes, str 1); 
бігі := concet('Bytes - header = ', str15; 
doMessageC'Logical EOF Odd', бігі, ‘Not a MacPeint 


(HEADER BLOCK NOT NEEDED) 


Ріта; 
(goto 1; try enyway!) 
END 
LSE 
BEGIN 


NumToString(bytes, str1); 
stri := concet('Bytes - header =', str1); 


doMessage( Reading Paint type...', stri, '', ©); 


PackedBitsPtr := NewPtr(bytes); (MAKE A HOME FOR DATA) 
IF MemError © noErr THEN 
BEGI 
PackedBitsPtr := NIL; 
doMessage( 'PackBitsPtr Memory err’, ‘ReadPaintFile 
routine’, "Мо room to read in data’, ''); 
GOTO 1; 


END; 
err := SetFPos(refNum, FSFromStert, 512); ( BEGIN OF DATA) 
IF err € noErr THEN 
BEGIN 
doMessageC'SetFPos error', ‘'ReadPaintFile routine’, 
‘Could not set file ', ‘at start of data’); 
END; 
err := FSRead(refNum, bytes, PackedBitsPtr); (READ IT) 
IF err © noErr THEN 
BEGIN 
doMessage('FSRead error', 'ReadPaintFile routine’, 
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‘Problem reading in file', ‘'); 
GOTO 1; 
END; 


1: 

END; (ReadPaintF ile) 

PROCEDURE GetPaintImage; ( (ver ImagePtr : Ріг)) 
LABEL 


2; 
CONST 
SizeOfPaintImage = 51840; 
AR 


refNum : Integer; 
theReply : SFReply; 
err : OSErr; 
peckedBitsPtr : Ptr; 
destPtr, SrcPtr : Ptr; 
saveStert : longInt; 
bytesUnPacked : Integer; 
BEGIN 
ImagePtr := NIL; 
SFGetPaintCtheReply); 
WITH theReply 00 
IF NOT good THEN 
GOTO 2 
ELSE 
BEGIN 
err := FSOpen(fName, vRefNum, refNum); 
IF err «> 0 THEN 
BEGIN 
doMessage('FSOpen error on file', 
‘GetPaintImage routine’, "Сап not Open File ', ''); 
GOTO 2; 
END; 
ReedPaintF ileCrefNum, packedBitsPtr); 
( RETURNS А POINTER TO THE PACKED DATA ) 
Close0ldFileCrefNum, vRefNum); ( CLOSE 
FILE IMMEDIATELY ) 
IF packedBitsPtr = NIL THEN 
BEGIN 


GOTO 2; 
END; 
ImagePtr := NewPtr(SizeOfPaintImage); (THE IMAGE) 
IF MemError « 0 THEN 
BEGIN 
doMessage('ImagePtr Memory err', 'GetPaintImage 
routine', ‘No room for image’, ''); 
GOTO 2; 
END; 


(POINTERS TO BE USED BY UNPACKBITS INCREMENTED, SO SAVE) 
(OLD POINTERS BY CREATING SCAPEGOATS: SRCPTR AND DESTPTR) 
SrcPtr := packedBitsPtr; (SRCPTR WILL BE INCREMENTED) 
DestPtr := ImagePtr; (DESTPTR WILL BE INCREMENTED) 
(A PAINT IMAGE HAS MORE BYTES THAN CAN BE REPRESENTED BY AN) 
(INTEGER, AND UNPACKBITS ACCEPTS ONLY INTEGERS, SO UNPACK) 
(ONLY HALF THE BYTES AT А TIME.) 
saveStart := ord(DestPtr); 
UnpackBits(SrcPtr, DestPtr ,SizeOfPaintImage DIV 2); 
bytesUnPacked := ord(DestPtr) - saveStart; 
(THE FINAL UNPACKING STARTS FROM THE NEW VALUES OF SRCPTR.) 
UnpackBits(SrcPtr, DestPtr, SizeOfPaintImage - 
bytesUnPacked); 
DisposP tr (packedBitsPtr); 


7 


2: 

END; (GetPaint Image} 

PROCEDURE DisplayPaintFile; (CImagePtr : Ptr2;) 
LABEL 


VAR 
pageBits : BitMap; 
drewRect : Rect; 
Screen : Rect; 
BEGIN 
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Program Messages 
100 100 200 400 


Visible NoGoAway PR 
| Type ICN® = СМІ. 


BtnItem Enabled 
65 230 95 285 


StatText Disabled 
15 60 85 222 
*^0N20D^ 1\00^2\00^3 


IconItem Disebled 
19 10 42 42 


IF ImagePtr = NIL THEN 
BEGIN 
GOTO 3; 


END; 

(SET UP AN APPROPRIATE BITMAP TO SEND TO COPYBITS) 

WITH pageBits DO 

BEGIN 
baseAddr := ImagePtr; (GIVE THE BUFFER TO THE BITMAP) 
rowBytes := 72; (ROWBYTES OF PAINT IMAGE) 
SetRect(bounds, 0, 0, 576, 720); (ENCLOSES PAINT IMAGE) 


M 
(ASSUMES THE MAIN PROGRAM HAS OPENED А WINDOW APPROX) 
(THE SAME SIZE AS THE SCREEN AND SET THE PORT) 
Screen := screenBits.bounds; 
setRect(drawRect, screen.left + 148, screen.top + 0, 
Screen.right - 148, screen.bottom - 72); 

(3/8 image bounds size) 
copyBits(pageBits, thePort^.portbits, pagebits.bounds, 
drewRect, srcCopy, NIL); 


3. 
END; (DisplayPeintFile) 
END. (of unit) 


*PaintReader .R 
x 


PaintReader .RSRC 
APPLPAIN 


Type PAIN = STR 
‚0 
9 by MacTutor 1 MAY 1987 
Type FREF 
,128 
APPL 0 


, 129 
PICT 1 


9 128 1 129 


* ------- Dialogs -------- — 


| 
* Program Messages Dialog box... Ry 
type DLOG — 


,258 


д 


.H 
0001 0000 0002 8000 0004 4000 0008 2000 
0010 1000 0021 0800 0043 8400 0087 C200 


type DITL 010Ғ E100 0217 (080 042Ғ 8040 085Е 0020 


,258 10АЕ 0010 2054 0008 4008 3Ғ04 8010 4082 
4000 8041 2TEF FF22 ІҒҒ  1Ғ14 3FF1 FFOF 
37F1 3Ғ07 7DEF 9-07 4180 8007 0080 6007 
0040 ІҒЕТ 0020 021Ғ 0010 0407 0008 0800 
0004 1000 0002 2000 0001 4000 0000 8000 
x 

0001 0000 0003 8000 0007 С000 000Ғ Е000 
001Е Ғ000 003Ғ Ғ800 007Ғ FCOO GOFF FEBO 
ØIFF ҒҒ00 O3FF ҒҒ80 OTFF FFCÓ OFFF FFEO 
IFFF FFFÜ 3FFF FFF8 7FFF FFFC FFFF FFFE 
FFFF FFFF FFFF FFFE BFFF FFFC ТЕРЕ FFFF 
FFFF FFFF FFFF FFFF ТЕЕЕ FFFF ФЕРЕ FFFF 
Ø2FF FFFF Ø17F FFFF 00BF FFFF 005Ғ Е830 
002Е Ғ000 0017 Е000 0008 С000 0005 8000 
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Programmer s Workshop 
Implementing Undo For Text Edit 


Undo (Ста-2) It! 

Honored more in the breech than not is the standard Edit 
Menu Apple published in Inside Macintosh (page I-58). Even if 
a program does contain an Edit Menu with the recommended 
items, Undo might not really be available. 

An Undo command is a very helpful feature, especially if 
you just did Clear when you meantto do Cut or if you backspaced 
one word too many or whatever! It is remarkable that Undo is not 
included in all editing type programs because it is not that 
difficult to program. I designed and coded a text-file version for 
my own development system in less that two weeks. I modeled 
my Undo by observing the behavior of MacWrite. 

We want to give the user the following Undo capabilities: 
Undo Cut: 

е  Reinsert the cut text from the clipboard. 
e Restore the previous contents of the clipboard. 
Undo Copy: 
e Restore the previous contents of the clipboard. 
Undo Paste: 
е Remove pasted text. 
е Reinsert the text overlaid by Paste. 
Undo Clear: 
е Reinsert the text removed by Clear. 
Undo Typing: 
е Remove all characters typed since the user made the 
last selection. 
е Reinsert the selection overlaid by the typing includ- 
ing any removed by backspacing. 

For each Undo operation except copy, we also must reset the 
selection as it was before the user requested the "undid" opera- 
tion. 

Redo Cut, Copy, Paste, and Clear are straightforward. We 
merely perform a Cut, Copy, Paste, or Clear. However, for 
Redo Typing, we must: 

° Remove the current selection. 

e Remove any characters that the user had backspaced over. 

e Reinsert the "effective" typing sequence that the user 
Undid. 

The effective typing sequence is the string of characters 
remaining after the user backspaced. That is, if the text and 
selection had been as follows: 


His program is а 896 
and the user had typed: 
{backspace}{backspace}the most user- 
dis{backspace}{backspace}{backspace}un 
resulting in 


friendly program 
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Pascal 


His program is the most user-unffriendly program 
then the effective typing sequence is 
the most user-un 
If the user requested Undo Typing, the text and selection 
would revert to 


His program is a Ыш 


friendly program 


and if the user followed the request with Redo Typing, the 
text and selection would once again become: 


His program is the most user-unfriendly program 


To make sure that we can undo an operation, we have to save 
any information that the operation destroys. So, our edit opera- 
tions are: 

Cut 
e Save current contents of clipboard. 
е (Си сштеп selection to clipboard. 
e Set menu to Undo Cut. 
Copy 
e Save current contents of clipboard, 
• Copy current selection to clipboard, and 
e Set menu to Undo Copy. 
Paste 
e Save current selection, 
e Paste clipboard to current selection, and 
e Set menu to Undo Paste. 
Clear 
e Save current selection, 
е Delete current selection, and 
e Set menu to Undo Clear. 
Typing 
e If first character for selection: 
Save current selection. 
e If backspace over previously unsaved character: 
Insert unsaved character at beginning of saved 
selection. 
e Insert character in text at insertion point. 
е Set menu to Undo Typing. 

Note that I use the term clipboard to refer to the TextEdit 
scrap, not the clipboard file. To actually put the TextEdit scrap 
in the clipboard file (also called the desk scrap) you must call 
TEtoScrap. Toread the clipboard to the TextEdit scrap you must 
call TEfromScrap. 

The key design elements for undo (and redo) are a state 
variable for the next possible undo operation and a second Text 
Edit record. We use the state variable to reset the Undo item of 
the Edit Menu and to call the proper procedure when the user 
requests Undo. We use the second Text Edit record as a private 
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scrap area to save the text removed by the user's last editing 
operation. We can then use the various TextEdit procedures to 
move text from the clipboard to the private scrap or vice versa. 

To try out some simple versions of these undoable editing 
routines, we will write a very simple editing program. The 
program allows the user to selecta file, opens a window, reads the 
contents of the file into the window, and then allows the user to 
change thecontents of the window by typing, by using the mouse, 
and by selecting from the Edit menu. The program allows the 
user to close the window and open another from the File menu. 
The program's File menu also contains a Quit entry. 

If you are familiar with writing Macintosh stand-alone 
applications, you might want to skip over the next section to 
Editing Functions. 

To keep the program simple, we will ignore many expected 
Macintosh features such as desk accessories, moving the window 
on the screen, scrolling the text, and making the program easily 
translatable from English. We will not check for many possible 
error situations. 

Thus, our main program is: 

Initialize tool box, 
Initialize program's global variables, 
Initialize menus, and 
Start the main event loop. 
Our main event loop checks only for four events: 
activate: 
If window open calls TEActivate. 
mouse down: 
If in menu, calls menu selector 
Else if window open calls TE selector. 


key down and auto key: 
If window open calls typing routine 
Our main event loop continues to look for these events until 
the menu selector sets the global variable Quit to TRUE. When 
Quit is TRUE, the main event loop returns to our main program 
which terminates. 
Our menu selector: 
Determines which menu item was selected, 
If Apple menu, ignores it, 
If File Menu, calls File Manager with item, or 
If Edit Menu, calls Edit Manager with the item. 
Removes highlighting from menu bar. 
Our File Manager calls FileOpen or FileClose according to 
the item selected. That is, 
If Open, calis OpenFile, 
If Close, calls Close File, and 
If Quit, then 
If a file is open, calls Close_File, 
Sets QuitFlag to TRUE. 
Open-File 
Asks the user to select a file from a list; 
Opens the requested file; 
Opens a window to display the text of the file; 
Opens а TextEdit record to control display of 
the text; 
Opens а TextEdit record for the screp; 
Reads text of the file into TextEdit record; 


262 


Disables the Open item and enables Close item; 

The only error condition that we will check is if the user 
clicked the cancel button in the file dialog box. Note that if the 
file contains more than 32,767 characters, then our program may 
hang. TEInsert does not check for this limit and may never return. 
[The 32K limit is notorious throughout Text Edit, especially in 
TEScroll. This has not been changed in the SE & Mac П ROMS 
unfortunately. -Ed] 

Close File does almost the reverse of Open File. It: 

Closes the display TextEdit record, 

Closes the screp TextEdit record, 

Closes the window, 

Closes the file, and 

Enables the Open item and disables Close item. 


If we allowed the user to actually change the file, then we 
would have to rewrite the text and flush the volume also. Without 
considering the editing portion of our program, we need the 
following global variables: 


Pointer for the window, 

Hendle for the TextEdit record, 

Handle for the scrap TextEdit record, 
Integer for the file reference number, and 
Boolean for the Quit flag. 


Our first program in TML Pascal is then shown in listing 
one. 


PROGRAM UndoIt; 


(Program to test Edit menu including Undo/Redo of previous 
operation) 


($L UndoIt/Rsrc) 


($1 Memtypes. Ipas ) 
($1 QuickDraw. Іраѕ) 
($I OSIntf.Ipes } 
($1 ToolIntf.Ipas ) 
($I PackIntf.Ipas ) 


CONST MenuBar ID = 200; 
Fi leMenu 
Open! tem 
Closeltem 
QuitItem 
EditMenu 
UndoItem 
CutI tem 
Copy! tem 
Pastel tem 
Clear Item 
WindowID 


н 
NO 
к 
с 

о we 


(Global variables) 


VAR theWindow : WindowPtr; (Main window) 


DisplayTE : TEHandle; (TextEdit record for display) 
ScrapTE : TEHendle; (TextEdit record for scrap) 

f Num : integer; (Ref number for current file} 
QuitFlag  : Booleen; (Main event loop exits when TRUE) 
FileHandle : MenuHandle; 

EditHendle : MenuHendle; 


PROCEDURE Init MyGlobals; 


BEGIN 
QuitFlag:-FALSE; 
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theWindow:=NIL; (sNIL if no window opened) CloseItem:Close_File; 


END; (Init.MyGlobals) QuitItem: 
BEGIN 
PROCEDURE Open ile; IF theWindowONIL THEN 
Close_File; 
CONST hCorner = 99; Qui tF lag :=TRUE; 
vCorner = 90; END; 
MaxTEText = 32767; (Should be smaller for 128K Mac} OTHERWISE 
END; (CASE Menu! tem) 
VAR OpenReply : SFReply; END; (File_Manager } 
GetWhere : Point; 
f Types : SFTypeL ist; PROCEDURE Cut; 
ОрепЕгг : OSErr; 
TextRect : Весі; BEGIN 
TextLength : LongInt; END; (Cut) 
TextDest : Ptr; 
PROCEDURE Copy; 
BEGIN 
GetWhere.h:=hCorner; BEGIN 
GetWhere.v:=vCorner; END; (Copy) 
ГТурев101:- TEXT'; 
OpenErr :=-1; (Set to other than noErr) PROCEDURE Peste; 


SFGetFileCGetWhere, '',NIL, 1,f Types, NIL, OpenReply2; 


WITH OpenReply DO BEGIN 
IF Good THEN END; (Peste) 
OpenErr :=FSOpen(f Name, vRef Num, f Num); 
IF SRL EINE THEN PROCEDURE Cleer; 
BEGIN 
theWindow:zGetNewWindowCwindowID,NIL, WindowPtr(-12); BEGIN 
SetPor t( theWindow); END; (Clear) 
TextRect : ztheW indow^ .portRect ; 
DisplayTE :=TENew( TextRect, TextRect); PROCEDURE Undo; 
WITH TextRect DO (Make ScrapTE "invisible") 
BEGIN BEGIN 
top :=-bottom; END; (Undo) 
lef t:=-right; 
bottom :=0; PROCEDURE Edit Manager CMenuItem: integer); 
right :=0; 
END; BEGIN 
ScrapTE:=TENew( TextRect, TextRect); CASE MenuItem OF 
OpenErr :=GetEof CfNum, TextLength); Undol tem: 
IF TextLength»MexTEText THEN (Ensure "not too much") Undo; 
TextLength :=MaxTEText; CutI tem: 
Tex tDest : =NewP tr (CTextLength); Cut; 
OpenErr:sSetFPosCfNum,fsFromStart,0); {read text) Сору tem: 
OpenErr :=FSRead(fNum, TextLength, TextDest); Copy; 
TEInsert(TextDest, TextLength, DisplayTE); Pastel tem: 
DisposPtr(TextDest); Paste; 
EnebleItemCF i leHandle, Closel tem); END; (CASE Menu! tem) 
Disable! temCFi leHandle, OpenI tem); END; (Edit Manager) 
END; (IF ОрепЕгг=поЕгг) 
END; (Open File) PROCEDURE Menu. Selector(where:Point;VAR QuitFlag:boolean); 
PROCEDURE Close_File; VAR theCode : LongInt; 
MenuNum,MenuItem : integer; 
VAR CloseErr : OSErr; 
BEGIN 
BEGIN theCode : -MenuSelect(where); 
HideWindowCtheWindow); MenuNum : =HiWord( theCode ); 
TEDisposeCDisplayTE); Menul tem: =LoWord( theCode ); 
TEDispose(ScrapTE); Case MenuNum ОҒ 
DisposeW indow( theW indow); FileMenu:F i 1e_Manager (Menu! tem, Qui tFlag); 
theW indow : =NIL; EditMenu :Edit_Manager(Menul tem); 
CloseErr:-FSCloseCfNum); OTHERWISE 
EnebleItemCFileHandle,OpenItem); END; (CASE OF MenuNum) 
DisebleItem(CF i leHendle,CloseItem); HiliteMenuC0); 
END; (Close.File) END; (Menu Selector) 
PROCEDURE File. Manager(MenuItem: integer ; VAR PROCEDURE ТЕ Selector(where:Point;extend:Boolean); 
Qui tFlag:Boolean); 
BEGIN 
BEGIN END; (TE_Selector) 
CASE MenuItem OF 
OpenItem:Open.F ile; PROCEDURE TypistCEventMessage :LongInt); 
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BEGIN 
END; (Typist) 


PROCEDURE MainEventLoop; 


MainEvent : EventRecord; 
theCode : integer; 
extend : Boolean; 
enyWindow : WindowPtr; 


BEGIN (MainEventLoop) 
REPEAT 
IF GetNextEventCeveryEvent, MainEvent) THEN 
CASE MainEvent.what OF 
activateEvt: 
IF theWindowONIL THEN 
TEActivate(DisplayTE); 
mouseDown: 
BEGIN 
theCode : =F indW indow(MainEvent .where, апу indow); 
CASE theCode OF 
inMenuBar : 
Menu_Se lector (Ma inEvent . where, Qui tF lag); 
inContent: {Assume only one window) 
BEGIN 
extend :=(Bi tAnd(MainEvent . modif iers, Shif tKeu20 0); 
{If user holding shift key, then extended 
selection) 
TE_Se lector (MainEvent.where, extend); 


OTHERWISE (Ignore) 
END; (CASE theCode) 
END; (mouseDown) 
keyDown, autoKey: (ignores command key) 
IF theWindow<>NIL THEN 
Typist(MainEvent . message); 
OTHERWISE 
END; (IF GetNextEvent, CASE MainEvent. what) 
UNTIL QuitF lag; 
END; (MainEventLoop) 


FUNCTION Init. MyMenus :Boolean; 
CONST MenuBar Id = 200; 
VAR theMenuBar : Handle; (MBAR resource points to menus) 


BEGIN 
Init MyMenus: =FALSE ; (Assume menus not initialized) 
theMenuBar : =Ge tNewMBar (MenuBar Id); 
IF theMenuBer ONIL THEN 
BEGIN 
Se tMenuBar( theMenuBar ) ; 
DrawMenuBar ; 
Fi leHandle:=GetMHandle(FileMenu); 
Edi tHandle : =Ge tMHandle(Edi Меги); 
Ini t_MyMenus : =TRUE; 


END; 
END; (Ini t_MyMenus) 


BEGIN (Main Program) 
InitGraf CéthePor t); 
InitFonts; 
InitWindows; 
InitMenus; 
TEInit; 
InitDialogs(NIL); 
InitCursor ; 
Init_MyGlobals; 
FlushEvents(EveryEvent, 9); 
IF Init_MyMenus THEN 
MainEventLoop; 

END. (Main Program} 
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The resource file for this program is shown in listing two. 
* UndoIt/Rsrc.R - Resource definition of UndoIt 
UndoIt/Rsrc .ге1 
TYPE MBAR-GNRL 


,200 j; Resource ID 

‚1 3, Integers follow 
3 ;; Three menu items; 
1 j; Apple Menu 

200 33 File Menu 

201 j; Edit Menu 

TYPE MENU 

‚1 3, Apple Menu 

\14 

‚ 200 33 File Menu 
File 

Open 

(Close  ;; Initially disabled 
(- 

Quit 

‚201 3, Edit Menu 
Edit 

(Can't Undo ;; Disable at beginning 
(- 

(Cut 

(Сору 

(Peste 


(Clear  ;; Full standard edit menu should also include 
3, Select All and Show Clipboard 


TYPE WINDOW 
,200 
No Title ;; If title is only blanks, RMaker can crash 
40 20 300 480 
Visible NoGoAway 
2 ;, Plain Box 
0 


Editing Functions 

We now continue by doing the traditional editing functions: 
Cut, Copy, Paste, and Clear. We need a state variable to let us 
know what the next possible Undo or Redo operation is. For this 


we define: 

TYPE EditType = CCentUndo, UndoTyp ing, UndoCut , UndoCopy, 
UndoPaste , UndoCleer , 
RedoTyping, RedoCut, RedoCopy, 
RedoPaste ,RedoClear ); 


and add the variable EditStatus of EditType. 

To switch the text of the menu according to the current value 
of EditStatus, we need several string constants. These really 
should be in the resource file, but for brevity we put them directly 


in the program. These strings are: 
CONST CantUndoStr = 'Can''t Undo'; (Note double apostrophe} 
UndoS tr ‘Undo’ ; 


RedoStr = ‘Redo’; 
TypingStr = ‘Typing'; 


The remainder, Cut, Copy, Paste, and Clear we can take 
from the menu itself. 


We need two global variables to save the start and end of the 
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selection to be redone. Because the user can backspace over text 
in front of the previous selection, we also need a global variable 
to save the farthest point which the user backspaced to. These 
variables are: 


VAR 
UndoStart : integer; (Start previous/current selection) 
UndoEnd  :integer; (End previous/current selection) 


CurrentStart: integer; (Backspace point before previous 
selection) 
With these variables defined, we can write our TE Selector 
procedure for when the user clicks the mouse in the window. 
TE Selector 
Calls TEClick to set the selection in the TextEdit record, and 
Calls Reset, EditMenu to set Undo to Can't Undo. 
Reset, EditMenu is called with an EditType parameter and 
If the Clipboard contains text then 
Enables the Paste item 
Else 
Disables the Paste item; 
If the selection is more than the insertion point, 
Enables the Cut, Copy, and Clear items 
Else 
Disables the Cut, Copy, and Clear items; 
Sets the Edit status to the value of the parameter; 
If the parameter is CantUndo 
Sets Undo item to Can't Undo 
Else if Undo Typing or Redo Typing 
Sets Undo item appropriately, 
Else 
Get the text of the corresponding menu item, and 
Sets Undo item appropriately; 
If the paramter is CantUndo 
Disable Undo item 
Else 
Enable Undo item; 
So, we fill out ТЕ Selector іп our program above as: 


PROCEDURE ТЕ Selector(where:Point;extend:Boolean); 


BEGIN 
SetPort( theWindow); {Ensure port is text window) 
GlobaltoLocal (where); (Make mouse local to window) 
TEClickCwhere, extend, Disp laylE); 
Reset FditMenuCCantUndo); 
END; (TE Selector) 


and we add Reset_EditMenu, placing it before Cut. 
PROCEDURE Reset. EditMenuCUndoState :Edi t Type); 


VAR theStr : §tr255; 
theItem : integer; 
BEGIN 


IF TEGetScrepLen? THEN (Set Paste according to scrap} 
EnableCEdi tHandle,PasteItem) 
ELSE 
DisableCEditHandle,PasteItem); 
WITH DisplayTE^^ DO 
IF SelStart«SelEnd THEN (Set Cut, Copy, Clear according) 
BEGIN (to selection size 
EnableCEdi tHandle, CutI tem); 
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EnableCEditHandle, Copy! tem); 
EnableCEditHandle, ClearItem); 


DisebleCEdi tHandle,CutItem); 
DisebleCEdi tHandle, Copy! tem); 
Disab leCEditHandle,Clear Item); 
END; 
EditStatus:-UndoState; 
IF EditStatus=CantUndo THEN 
theStr :=CantUndoStr 
ELSE IF EditStatus IN (UndoTyping, RedoTyping] THEN 
ера 


BEGIN 
CASE EditStatus OF 
UndoCut, RedoCut : 
іһе tem: =CutI tem; 
UndoCopy, RedoCopy : 
thel tem: =Copy! tem; 
UndoPaste,RedoPaste: 
theI tem: =Pastel tem; 
UndoC lear ,RedoC lear : 
theI tem:=Clear Item; 
OTHERWISE 
END; (CASE EditStetus) 
GetItemCEditHandle, theItem, theStr ; 
END; (IF EditStetus) 
IF EditStatus IN [UndoTyping. .UndoClear] THEN 
theStr:=ConcatCUndoStr,* ',theStr) 
ELSE IF EditStatus IN [RedoTyping. .RedoClear] THEN 
theStr :=Concat(RedoStr,' ',theStr); 
Set I temCEdi tHandle, Undo! tem, theStr); 
IF EditStatus=CantUndo THEN 
Таныды 
(5 


(Cet item number to Undo/Redo) 


(Reset Undo item) 
(Disable Can't Undo or) 


EnableCEdi tHandle,UndoItem); (Enable Undo/Redo ) 


END; (Reset EditMenu) 


Have you often thought that "These writers dash off pro- 
grams so easily, how do they do it?" Well, in many cases they 
don't. They just don't bother telling you all their struggles to find 
the typo or the minus sign that should have been a plus sign. In 
this particular case, I spent an hour trying to figure out why no 
caret appeared and why clicking on the mouse highlighted a new 
area, but did not unhighlight the old area. 

Ireadandreread about TEClick in both Inside Macintosh and 
Macintosh Revealed. I could not understand what I was doing 
wrong. Then I remembered a similar problem from long ago; to 
make the TextEdit procedure I was using work, I had to call 
TEActivate. For this program, I could have called TEActivate 
rightafter the call to TENew and that would have been sufficient, 
but I went back and added a new event test in MainEventLoop. 
So what you see now as the first try at the program was really the 
n-th try. Most programs don't have this problem because, 
whenever a window is activated, the program also activates any 
associated TextEdit record. 

After I fixed the program, I saw the note on the middle of page 
I-383 of Inside Macintosh. [This is a common frustration; you 
spend hours finally fixing the problem, only to discover it later in 
Inside Macintosh, AFTER you know what to look for! -Ed] 

Other problems that I encountered while writing this program 
are summarized at the end of this article under "What Can Go 
Wrong". 
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Continuing, we now write write the procedures Cut, Copy, 
Paste, and Clear. These are: 
Cut 
Save selection points, 
If selection greater than an insertion point 
е Paste Clipboard to ScrapTE, 
• Cut current selection to Clipboard, 
e Set Undo item to Undo Cut, 
e Enable Undo and Paste items, and 
e Disable Cut item. 
Copy 
Save selection points, 
If selection greater than an insertion point 
e Paste Clipboard to ScrapTE, 
• Сору current selection to Clipboard, 
¢ Set Undo item to Undo Copy, and 
е Enable Undo item. 
Paste 
e Save selection points, 
e Delete ScrapTE text, 
• Copy current selection to ScrapTE, 
e Paste Clipboard to current selection, 
• Set Undo item to Undo Paste, and 
e Enable Undo item. 
Clear 
Save selection points, 
If selection greater than an insertion point 
e Delete ScrapTE text, 
• Сору current selection to ScrapTE, 
е Delete current selection, 
4 Set Undo item to Undo Copy, and 
e Enable Undo item. 
Writing these in Pascal, we add before Cut: 


PROCEDURE Save_EndPoints; (Save selection points) 


BEGIN 
WITH DisplayTE^^ DO 
BEGIN 


UndoStart :=SelStart; 
UndoEnd :=SelEnd; 
CurrentStart:=UndoStart; 
END; 

END (Save Selection) 


PROCEDURE Seve. C1 ipboard; 

BEGIN 
TESetSelect(@, ScrepTE^^ . TELength, ScrapTE); 
TEPasteCScrepTE); 

END; (Save Clipboard) 

PROCEDURE Delete. 5сгарТЕ; 

BEGIN 
TESetSelect(0, ScrapTE^^ . TELength, ScrapTE); 
TEDeleteCScrapTE); 

END; (Delete.ScrepTE) 

PROCEDURE Save. SelectionCtheStart, theEnd); 

BEGIN 
IF theStart«theEnd THEN 
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BEGIN 


HLockCHendleCDisplagTE2); 
WITH DisplayTE^^ DO 


BEGIN : 
HLockChText); Display Te 
TEInsertCPtrCOrd4ChText^ )+theStart, 

theEnd-theStart,ScrapTE); 
HUnlockChText); 
END; 


HUnlockCHendle(CDisplayTE)); 
END; 
END; (Save.Selection) 


Clipboard 
and replace Cut, Copy, Paste, and Clear with: 


Coia ЖИН, 
PROCEDURE Cut; 


Undo Cut 
BEGIN 
Save_EndPoints; 
Save. Clipboard; (Save old clipboard) 
TECut(DisplayTE); (Cut selection to clipboard) 
Reset. FditMenuCUndoCut); 

END; (Cut) 


PROCEDURE Copy; 


Display TE 
BEGIN 
Save EndPoints; 
Save. Clipboard; (Seve old clipboard) 
TECopy(DisplayTE); (Copy selection to clipboard) 
Reset_EditMenuCUndoCopy); 
END; (Copy 


SerapTE 


Clipboard 
PROCEDURE Paste; 


ScrapTE 
BEGIN 
Save_EndPoints; 
Delete_ScrapTE; 


Undo Copy 
Seve. SelectionCUndoStart , UndoEnd); 
TEPaste(DisplayTE); 


(Paste selection from clipboard) 
Reset EditMenuCUndoPaste); 
END; (Paste) 


PROCEDURE Clear; 


DisplayTE 
BEGIN 

Save_EndPoints; 

Delete_ScrapTE; 


Save_Se lect ion(UndoStart , UndoEnd); 
TEDelete(DisplayTE); 


(Delete current selection) 
Reset FditMenuCUndoClear); 
END; (Clear) 


Clipboard 
Undo Operations 


Undo Paste 


Now we have most of the tools in place to undo cut, copy, 
paste, or clear. With Undo we can now restore both the text and 
the clipboard as they were before the user requested the operation 
to be undone. For the undo operations except Undo Typing, we 
need to: 
Undo Cut: 


` 
e 


= 
Paste clipboard to insertion point, 
Reset selection, 

Copy ScrapTE to clipboard, 


Set Undo item to Redo Cut, and 
Enable all edit items. 
Undo Copy: 
• Cut ScrapTE to clipboard, 
Set Undo item to Redo Copy, and 


Display TE 
e 


Clipboard SerapTE 


Undo Clear 
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* Enable all edit items. 
Undo Paste: 
* Reset selection to pasted text, 
e Delete selection, 
е (Сору ScrapTE to selection 
е Reset selection to previous text, 
e Set Undo item to Redo Paste, and 
e If selection greater than insertion point 
Enable all edit items 
Else 
Enable Undo and Paste items. 
Undo Clear: 
e Copy ScrapTE to selection 
e Reset selection, 
e Set Undo item to Redo Clear, and 
e Enable all edit items. 
For common subroutines for undo operations, we add to 
the group of Save Procedures: 


PROCEDURE Restore. Clipboard; 


BEGIN 
TESetSelect(0,ScrapTE^^ . TELength, ScrapTE); 
TECut(ScrapTE); (Also clears ScrepTE) 
END; (Restore Clipboard) 


PROCEDURE Restore. SelectionCtheLength: integer); 


BEGIN 
IF theLength»g THEN 
BEGIN 


HLock(HandleCScrapTE)); 

WITH ScrepTE^^ DO 

BEGIN 
HLockChText); (ScrapTE to insertion point) 
TEInsertCPtrCOrd4ChText^ 2, theLength,D isplayTE); 
HUnlockChText); 

END; 

HUnlockCHandleCScrapTE 2); 

END; (Restore. Selection) 


and replace Undo with all of the following: 
PROCEDURE Undo. Cut; 


BEGIN 
TEPesteCDisplayTE); (Restore text) 


TESetSelectCUndoStert,UndoEnd,DispleyTE); {Reset selection) 


Restore. Clipboerd; 
Reset. FditMenuCRedoCut); 
END; (Undo.Cut) 


PROCEDURE Undo. Copy; 


BEGIN 

Restore. Clipboard; 

Rese t_Edi tMenuCRedoCopy); 
END; (Undo_Copy) 


PROCEDURE Undo_Paste; 


BEGIN 

TESe tSe lect(UndoStart, Disp layTE** .SelEnd,DisplayTE); 
(Delete pasted text) 

(UndoStart is also beginning of pasted text) 
TEDeleteCDisplayTE); 

Restore. Selection(ScrapTE^^ . TELength); 


TESetSelect(UndoStart,UndoEnd,DisplayTE); (Reset selection) 


Delete ScrapTE; 
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Reset. Fdi tMenuCRedoPeste); 
END; (Undo.Peste) 


PROCEDURE Undo. Cleer ; 


BEGIN 

Restore. Selection(ScrapTE^^ . TELength); 
TESetSelect(UndoStart,UndoEnd,DisplayTE); (Reset selection) 
Delete_ScraplE; 

Reset_Edi tMenu(RedoClear ); 

END; (Undo.Cleer) 


PROCEDURE Undo. Typing; 


BEGIN 
END; (Undo. Typing) 


PROCEDURE Redo.- Typing; 


BEGIN 
END; (Redo_Typing) 


PROCEDURE Undo; 


BEGIN 
CASE EditStetus OF 
UndoCut : 
Undo. Cut; 
UndoCopy: 
Undo. Copy; 
UndoPaste: 
Undo_Paste; 
UndoC lear: 
Undo_C lear ; 
UndoTyping: 
Undo_Typing; 
RedoCut : 


RedoPaste: 
Paste; 
RedoC lear: 
Clear; 
RedoTyping: 
Redo_Typing; 
OTHERWISE 
END; (CASE EditStatus) 
END; (Undo) 


Typing 


Display TE 


Clipboard 


Typing 


Finally, we get to the most difficult, handling typing so that 
it is undoable. One would think that it is no more difficult than 
undoing any of the other editing operations. However, the 
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backspace key causes a problem. If the user backs over newly 
entered text, we have no problem. But when the user backs over 
previous text we must save the newly deleted character and the 
new beginning point. 

See the exampleat the beginning of the article for an example 
of backspacing over the previous text. 


For typing, we need to: 


е Check if user entered a meaningful character; 
е If EditStatus is not UndoTyping, then 
Save selection points; 
Delete ScrapTE text; 
Copy selection to ScrapTE; 
• If user entered backspace, then 
If not beginning of text and 
If all newly typed characters deleted, then 
Copy character preceding insertion point to 
beginning of ScrapTE; 
Decrement "current insertion point"; 
е Insert character entered by user in text; 
e If EditStatus is not UndoTyping, then 
Set Undo item to Undo Typing; 
Enable Undo item. 

Note that we cannot set Undo Typing under the first test of 
EditStatus because Reset EditMenu enables or disables the 
other item according to the size of the selection. If the selection 
is more than the insertion point, the first character inserted with 
TEKey into the text will delete the selection. 

Thus, we rewrite Typist as: 


PROCEDURE Typist; 


CONST Return = $00; 
Enter z $03; 
Backspace = $08; 
Tab = $09; 


TYPE Codes = 0..255; 


VAR KeyCode : integer; 
Char In : Cher; 
Charl : CharsHandle; 


AllowedCodes : SET OF Codes; 


BEGIN 
KeyCode : =B i tand(EventMessage , charCodeMask ); 
Al lowedCodes :=($20. .$7F ,Return, Enter , Backspace, Tab); 
(May be erroneous if used directly in TML Pascal 1.11} 
(See letter from Christopher Dunn in July 1986 MacTutor) 
IF KeyCode IN AllowedCodes THEN 
Char In: chr (KeyCode) 
ELSE 
KeyCode:=@; (Use КеуСобе-0) as test to bypass sections) 
IF EditStetusO UndoTyping THEN 
IF KeyCodeo0 THEN 
BEGIN 
Save EndPoints; 
Delete. ScrapTE; 
Save. SelectionCUndoStart , UndoEnd); 
END; (IF EditStatus<>UndoTyping, IF KeyCode o 2) 
IF KeyCode-Backspece THEN 
WITH DisplayTE** DO 
IF SelSterb THEN 
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3 (1) 
Display TE 
(2) 


= 


Clipboard 


Undo Typing 


" 
Display TE 
(2) 


Hs 


Clipboard ScrapTE 


Redo Typing 


IF SelEnd«sCurrentStert THEN 
BEGIN 


CharH:=TEGetText(DisplayTE); 
(Get the text as a character array) 
CurrentStart :=CurrentStart- 1; 
TESe tSe lect(8,8,ScrapTE); 
ы ы iL 
END; 
IF KeyCodeo 29 THEN 
BEGIN 
TEKey(CharIn,DisplayTE); 


IF EditStetus OUndoTyping THEN 
Reset. EditMenuCUndoTyp ing); 


END; 
END; (Typist) 


We now have the pieces in place to Undo or Redo any typing 
by the user. For Undo Typing we neeed to: 

е Move new typing to end of ScrapTE, 

е Delete new typing from DisplayTE, 

е Move previous selection to DisplayTE, 

е Set selection points to previous selection, 

е Delete previous selection from ScrapTE, and 

• Set Undo item to Undo Typing. 
For Redo Typing we need to: 

е Move previous selection to end of ScrapTE, 

е Delete previous selection from DisplayTE, 

е Move new typing to DisplayTE, 

e Delete new typing from ScrapTE, and 

« Set Undo item to Redo Typing. 

Hmm! Undo Typing and Redo Typing look very similar! 
They are, and in fact, we could merge them into one procedure. 
For clarity, we won't but will leave that as an exercise for... 
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Our final piece of code is to expand these by replacing 
Undo Typing and Кейо Typing. For Undo, Typing we have: 


PROCEDURE Undo. Typ ing; 
VAR screpLength : integer; 


TgpingEnd : integer; 
theText : Handle; 
BEGIN 


scrapLength:=ScrapTE**.TELength; (Put new type at scrap end) 
TESe tSe lect (scrapLength, scrapLength, ScrapTE); 
TypingEnd:=DisplayTE**.selEnd; 

IF CurrentStert«TypingEnd THEN 

BEGIN 


Save-SelectionCCurrentStert, TypingEnd); 
TESetSelect(CurrentStart, TypingEnd, DisplayTE); 
TEDelete(DisplayTE); (Delete new typing) 

END; (IF CurrentStart<Typ ingEnd) 
Restore_Selection(scrapLength); (Put orig selection back} 
TESetSe lect (UndoS tart, UndoEnd, Disp layTE); 
TESetSelect(0,scrapLength,ScrapTE); (Delete prev from scrap} 
TEDeleteCScrapTE); 

Reset. EditMenuCRedoTyp ing); 
END; (Undo_Typing) 


For Redo_Typing we have: 
PROCEDURE Redo_Typing; 
VAR scrapLength : integer; 


TypingEnd : integer; 
theText : Handle; 
BEGIN 


scrapLength:=ScrapTE**.TELength; (Put old select at end of) 
TESetSelect(scrapLength,scrapLength,ScrapTE);  (ScrapTE) 
TypingEnd:= DisplayTE**.selEnd; 
IF CurrentStart<TypingEnd THEN 
BEGIN 
Save_Selection(CurrentStart, TypingEnd); 
TESetSelect(CurrentStart, TypingEnd, Disp layTE); 
TEDeleteCDisplayTE); (Delete old selection) 
END; (IF CurrentStert«TypingEnd) 
Restore.Selection(screpLength); (Move new typing to 
DisplayTE) 
TESetSelect(£, scrapLength, ScrapTE); 
TEDeleteCScrapTE); (Delete new typing from ScrapTE) 
Reset. EditMenuCRedoTyp ing?; 
END; (Redo_Typ ing) 


That's it! Now you have an editor for very small files that 
allows the user to Undo each editing operation immediately after 
requesting the operation. But this is only the beginning of your 
work for an editor. Now you have to add: 

e Scrolling, 
e Window resizing, 
e Multiple windows, 
e Search and replace commands, 
e Additional error checking, and 
е Much more. 
[Note: Some of this capability was published in the first 
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article in this series on Text Edit in the January 1987 issue of 
MacTutor. -Ed] 

What Can Go Wrong 

This article is a bit deceptive. Because, I wrote it as a step- 
by-step approach, programming this small editor seems easy. 
However, I should admit that what you see is the third attempt. 
My first editor was the text editing support in DevHELPERG. 
My second editor was the first draft of this article, and I did it 
pretty much in the order given. My third editor is the program of 
this article with all the bugs out (or most obvious bugs), with little 
reorganizations to improve readability, and with common code 
put into separate procedures. 

When you write your editor, you may make some of the same 
mistakes that I did. To save you some of the grief of figuring out 
what went wrong, here are some mistakes that I recorded in my 
notes. 

* Immediate termination of program 
Did not call Init MyGlobals, thus did not set 
QuitFlag. 
e System Error 01,02 
Used theWindow in MainEventLoop as local variable, 
but did not declare it so. 
e Watch cursor shown before first menu selection 
Did not call InitCursor before or at beginning of 
MainEventLoop. 
e Selection is "checkerboard" of highlighting 
Did not call GlobaltoLocal for mousepoint. 
e No blinking caret 
Did not call TEActivate after TENew. 
е Hang on Cut 
viewRect and destRect for ScrapTE were "illegal" 
rectangles, that is, top» bottom or right>left. 
* Undo Paste using wrong text: 
ScrapTE not cleared by earlier operation 
* Undo Paste not undoing: 
Scrap TE not cleared by earlier operation. 
e Slow typing 

Slow typoing can happen on a MacXL or a Mac with 128K. 
TEKey on these systems is too slow if it has to move several 
thousand characters which would happen at the beginning of 
large documents. TEKey on a Mac+ was not a problem on the 
same document in the same place. If you plan to write your editor 
for earlier machines, you may need to work with only a portion 
of the text. Now that we've begun to understand Text Edit, we get 
to start all over again, with the new text edit on the SE and 
Macintosh II! Look for more articles in this series in the coming 
months. 
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Macintosh П 
Lazy Man's Color 


Newsbreak....Cupertino, Calif.....Color is here! 

The new Macintosh // computer has color capabilities. Most 
color video cards will allow up to 256 specific colors out of a 
possible color palatte of 16,777,216 selections. A new Color 
Quickdraw has been designed with Color Tables, Pixel Maps, 
Pixel Patterns, Color Icons, Color Grafports and Color Picture 
Handles to work with the new machine. Three new Managers 
have been added to facilitate color; the Color Manager, the Color 
Picker Package and the Palette Manager. 

Are you ready to program with this new Color Quickdraw? 

Before you answer that, did you know there was an alternative 
way to display color on the Mac? Use the old Quickdraw color 
routine! You didn’t know the older Quickdraw had color? Well... 

Old Color 

The original Macintosh displays were in black & white. 
21,888 bytes of memory were used to display the normal 512 by 
342 pixel screen (1 bit per pixel). However, the original Quick- 
draw had the capability to draw in color. In the original Grafport 
record, there were 2 fields (fgColor and bkColor) that determined 
the settings of the Foreground and Background color. 

Quickdraw predefined 8 colors (Black, White, Red, Green, 
Blue, Cyan, Magenta and Yellow). Each color had a long integer 
constant associated with it. By passing these constants to the 
procedures ForeColor and BackColor, the respective fields of the 
current Grafport were changed. When any Grafport was created, 
the default settings for the Foreground and Background were 
Black and White respectively. 

Color fields were treated similar to the more often used Pen 
Pattern (pnPat) and Background Pattern (bkPat). Any drawing 
by the Pen was done in the Foreground color, any Erasing was 
done in the Background color. Also Foreground and Background 
color affect the Copybits call. When copying a bitmap onto a 
Grafport, any bit that was set in the source Bitmap would make 
the corresponding pixel appear in the Foreground color on the 
Grafport. Any unset bit would make the pixel appear in the 
Background color. 

However on the black and white Macintosh, any color other 
than white appears as black. Thus drawing Red on White, Blue 
on White, or even Yellow on White has the same effect on the 
Pre-Mac // computers; Black on White. Interestingly the 
Imagewriter // printer driver does use the color commands, thus 
making the Imagewriter // with a color ribbon the first color 
Macintosh output device of any type. While the new Mac // also 
has the new Color Quickdraw commands, it also supports the old 
commands, including the use of Foreground and Background 
color. 

Why Use Old? 

There are several reasons for not wanting to use Color 
Quickdraw for your first color program. It might prove simpler, 
until you get a handle on Color Quickdraw (and the three 
associated managers), to use the older Quickdraw routines. 
Color Quickdraw involves new conceptional models, new data 
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structures, and new routines. While it is well worth the effort to 
learn (the graphic effects are stunning), there is a stiff learning 
curve. 

The Color Quickdraw manual is even larger than the original 
Quickdraw manual. That is assuming that you have the new 
documentation. Inside Macintosh Vol. V is due out soon, but 
unless you currently have a beta version, you will have to wait for 
АРПА” final release. 

Even if you have the new documentation and routines, your 
development system may not implement the new ROM calls. 
Lightspeed C, Lightspeed Pascal, MDS do not support the new 
Quickdraw, while MPW has to be updated to version 2.0. Many 
programmers will have to wait until the developers of their 
programming language come out with a new update until they 
can use the new routines. Some lucky users can input all the new 
calls themselves and do not need the updates. That means typing 
in dozens of new calls and data structures (again assuming they 
have the documentation). Lucky them! [Apple is still working on 
the equates file and rumor has it the Pallette Manager is still 
changing. -Ed] 

Finally there is the actual code size and time in involved 
programming the new Quickdraw. Color Quickdraw does take 
more code to implement and it’s data structures are larger. The 
simple ForeColor and BackColor routines take very little code 
space. 

Certainly Color Quickdraw should be used if someone is 
writing а color Drawing program for the Mac //. But if you only 
wish to add color to your existing programs, using Color Quick- 
draw requires you to rewrite your code, redo your graphics and 
in some cases, even redo your complicated bitmaps. Placing 
ForeColor and BackColor calls before your existing code seg- 
ments is much simpler. If your Program is intended to run on any 
Macintosh, the older Quickdraw may be all you need or want to 
produce color. 


The Code 
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The source example is an extremely simple, standard Macin- 
tosh program. It loads and displays any MacPaint document in 
any ofthe eight Foreground and eight Background colors. A few 
notes: 

1) The CWindow (which will display the MacPaint docu- 
ment) is centered on large screens (like a SuperMac 
monitor) or placed in the offset position. 

2) The actual picture is stored in two sets of Bitmaps and 
Data handles. Data is stored this way since the size of a 
MacPaint bitmap is too large to store in 1 set (32K limit). 
If there is not enough memory to create the bitmaps, the 
program will state this and not allow a MacPaint docu- 
ment to be loaded 

3) ForeC and BackC store the selected menu number (1-8), 
not the predefined Color constant. GetColor is used to 
convert the menu number into the color constant. 

4) DoColor is the pivotal procedure; it sets the new Fore- 
ground/Background colors. Then it causes an window 
update so the window is redrawn in the new colors. 


Lazy Man’s Color by Steve Sheets 4/20/87 ) 

Simple Demonstration of Mac // Color using the 
ForeColor & BackColor of classical Quickdrew. ) 

This program Loads and displays а MacPaint document ) 
in any 2 colors. ) 


PROGRAM LMC; 


Lan OREN ON >. 


( Various Constants: 
{ Window Placement, 
CONST 
AppleMenuID = 300; 
FileMenuID = 301; 
EditMenuID = 302: 
ForeMenuID = 303; 
BackMenuID = 304; 


Menu ID Numbers, Window Size, ) 
BitMap Size and Number of Colors. ) 


OffV = 40; 
OffH = 40; 
AboutH = 300; 
AboutV = 140; 
SizeH = 576; 
SizeV1 = 360; 
SizeV2 = 720; 


BitW = 72; 
NumSec = 2; 
XColor = 8; 


( Various Variables: Menus, Bitmaps, Window, Colors, } 
( Done Flag & Title Name ) 
VAR 

Done : boolean; 

AppleMenu, FileMenu: EditMenu, 

ForeMenu, BeckMenu : MenuHandle; 


CWindow : windowptr; 
CMap : ARRAY[1..NumSec] OF bitmap; 
CData : ARRAY[1..NumSec] OF handle; 


ForeC, BackC : integer; 
Title : str255; 


( Given Color Number С 1 to XColor, as selected by Menu), ) 
( returns actual longint Color Number (for ForeColor or ) 
( ВаскСо1ог). 
FUNCTION GetColor (N : integer) : longint; 
BEGIN 
А М ОЕ 
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GetColor := BlackColor; 


2з 

GetColor := WhiteColor; 
3: 

GetColor := RedColor; 
4: i 

GetColor := GreenColor; 
5: 

GetColor := BlueColor; 
6: 

GetColor := CyanColor; 
1: 

GetColor := MagentaColor; 
8: 

GetColor := YellowColor; 
OTHERWISE 

GetColor := WhiteColor; 

END; 


END; 


( Sets new ForeColor & BackColor and forces an Update} 
( 50 Window is redrawn in the new colors. ) 
PROCEDURE DoColor (F, B : integer); 
VAR 
count : integer; 
tempPort : Grafptr; 
BEGIN 
GetPortCtempPort); 
SetPor tCCWindow); 
IF F о ForeC THEN 
BEGIN 
FOR count := 1 TO XColor DO 
CheckItemCForeMenu, count, count s Р); 
ForeC := F; 
ForeColor(GetColor(ForeC 22; 


END; 
IF B © BackC THEN 
BEGIN 


FOR count := 1 TO XColor DO 
CheckItem(BackMenu, count, count = B); 

BackC := В; 

BackColorCGetColor(BackC22; 


InvalRect(CN indow" .portRect); 
Se tPor tCtenpPort); 
END; 


( Loads MacPaint Picture in Bitmaps and displays it.) 
PROCEDURE DoLoad; 
TYPE 


odios = PACKED ARRAY[1..512) OF QDbyte; 
MyReply : SFReply; 
MyType : SFtypelist; 
tempPoint : point; 
count : longint; 
refNum, scanline, М: 
error : OSErr; 
srcBuf : ARRAY[1..2) OF diskBlock; 
srcPtr, dstPtr : Ptr; 


integer; 


BEGIN 
tempPoint.v := 60; 
tempPoint.h := 60; 
М/Туре(01 := ‘PNTG’; 
SFGetFileCtempPoint, '^, NIL, 1, MyType, NIL, MyReply); 
IF MyReply.good THEN 
BEGIN 


HlockCCDataL[ 125; 

Hlock(CData(2)); 

IF FSOpen(MyReply.fname, MyReply.vrefnum, refNum) = 
noErr THEN 


BEGIN 
count := 512; 
error := FSRead(refNum, count, @srcBuf); 
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count := 1024; 
error := FSRead(refNum, count, @srcBuf ); 
srcPtr := @srcBuf; 
FOR N := 1 TO NunSec DO 
BEGIN 
dstPtr := CData[N]^; 
FOR scanline := 1 TO SizeV1 DO 
BEGIN 
UnpackBits(srcPtr, dstPtr, BitW); 
IF ord(srcPtr) > CordCésrcBuf) + 512) THEN 
BEGIN 
srcBuf [1] := srcBuf [2]; 
count := 512; 
error := FSRead(refNum, count, @srcBuf (21); 
srcPtr := pointerCord(srcPtr) - 512); 
END; 
END; 


error := FSCloseCref Num); 
END; 
HUnlockCCData[ 112; 
HUnlock(CCData (21); 
END; 
DoColor(ForeC, BackC); 
END; 


{ Creates a Rectangle centered on Screen Cif window ) 
( size is smaller then the screen) or starting at а) 
( standard offset Cif window size is larger then ) 
( screen). 
PROCEDURE CenterRect (VAR R : rect; 

H, V : integer); 


VAR 
tempH : integer; 
BEGIN 
IF H > Screenbits.bounds.right THEN 
tempH := OffH 
ELSE 


tempH := ((Screenbits.bounds.right - H) DIV 25; 
SetRect(R, tempH, OffV, Н + tempH, V + OffV); 
ND; 


s 


(  Drews text, centered in a rectangle in the About) 
( Вох window in a certain color with a certain ) 
( justification } 
PROCEDURE DoLine (S : str255; 
H, Top, Bottom, J : integer; 
C : longint); 
VAR 
tempInteger : integer; 
tempRect : rect; 
BEGIN 
ForeColor(C); 
tempInteger := CCAboutH - H) DIV 2); 
SetRect(tempRect, tempInteger, Top, tempInteger + H, 
Bottom); 
TextBox(POINTERCord(@S) + 1), LENGTHCS), tempRect, J); 
END; 


( Displays About Box Cin color) until someone presses ) 
( the button down. ) 
PROCEDURE DoAbout ; 

VAR 


tempWindow : windowptr; 
tempRect : rect; 
tempStr : str255; 
BEGIN 
CenterRectCtempRect, AboutH, AboutV); 


tempWindow := NewWindow(NIL, tempRect, '^, true, dBoxProc, 


POINTERC- 1), false, 0); 
SetPortCtempWindow); 
TextFont(0); 


DoLineCCONCATCTitle, ” by Steve Sheets’), AboutH, 20, 39, 
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teJustCenter, BlueColor); 

DoLineC'Sample Mac // Color Program’, AboutH, 40, 59, 
teJustCenter, GreenColor); 

DoLineC'This progrem uses the ForeColor and BeckColor 
Quickdraw commands to display a MacPaint document in two 
colors.^, AboutH - 50, 60, AboutV, teJustLeft, RedColor); 


WHILE NOT button DO 


DisposeW indow( tempW indow); 
END; 


{Standard main menu procedure that handles ) 
( menu selections. Can show About Box, open Desk ) 
(Accessories, Load in MacPaint file, change 
( the Done Flag (so the program quits), handle} 
( edit commands (Cut,Copy,Paste,Clear), and change ) 
( Foreground or Background color of the picture. 
PROCEDURE MainMenu CtempResult : LONGINT); 

VAR 


tempInteger : integer; 
tempBoolean : boolean; 
tempStr : STR255; 
BEGIN 
tempInteger := LoWordCtempResult); 
CASE HiWord( tempResult) OF 
AppleMenuID : 
IF tempInteger = 1 THEN 
DoAbout 
ELSE 
BEGIN 
GetItemCeppleMenu, tempInteger, tempStr); 
tempInteger := OpenDeskAcc(tempStr ); 
END; 
FileMenuID : 
= tempInteger OF 


' DoLoed; 


Done := true; 
OTHERWISE 
END; 
EditMenuID : 
tempBoolean := SystemEditCtempInteger - 1); 
ForeMenuID : 
IF CtenpInteger > 0) AND CtenpInteger <= XColor) THEN 
DoColorCtempInteger, BackC); 
BackMenuID : 
IF CtempInteger > 0) AND CtempInteger <= XColor) THEN 
DoColor(ForeC, tempInteger); 
OTHERWISE 
END; 
HiliteMenu(0); 
END; 


{ Setup for Menus, Window, Bitmaps, Colors ) 
( settings, Title and Done flag. 
PROCEDURE DoSetup; 

TYPE 


00 = PACKED ARRAY(1..32000] OF 9..255; 
PP = “DD; 
HH = “PP; 

VAR 


tempStr : STR255; 
tempRect : rect; 
count : integer; 
tempLong : longint; 
tempH : HH; 
BEGIN 
Title := ‘Lazy Manés Color’; 
Title[9] := CHR(39); 


tempStr := ' '; 
tempStr (1) := CHRCappleMark); 
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AppleMenu := NewMenuCAppleMenuID, tempStr); 
AppendMenuCAppleMenu, CONCATC'About ', Title, '...; C722; 
AddResMenuCAppleMenu, 'DRVR'); 


FileMenu := NewMenu(FileMenuID, ‘File’); 
AppendMenu(FileMenu, ‘Load MacPaint Documents/L; (- ;Quit/ 
Q’); 


EditMenu := NewMenu(EditMenuID, ‘Edit’); 
AppendMenu(CEditMenu, ‘Undo/Z;(-;Cut/X;Copy/C; Paste/ 
V;Clear’); 


ForeMenu := NewMenuCForeMenuID, ‘Set Foreground’); 
AppendMenu(ForeMenu, ‘Black;White;Red;Green;Blue; 
Cyan; Magenta; Yellow’); 


BackMenu := NewMenu(BackMenuID, ‘Set Background’); 
AppendMenu(BackMenu, ‘Black; White;Red;Green;Blue;Cyan; 
Magenta; Yellow’); 


InsertMenuCAppleMenu, 9); 
InsertMenu(CF ileMenu, 0); 
InsertMenuCEditMenu, 0); 
InsertMenuCForeMenu, 9); 
InsertMenu(BackMenu, 0); 


DrawMenuBar ; 


CenterRect(tempRect, SizeH, SizeV2); 
CWindow := NewWindow(NIL, tempRect, Title, true, 4, 
POINTER(-1), false, 0); 


CMap[1].rowBytes := BitW; 
SetRect(CMap[1].bounds, 0, 0, SizeH, SizeV1); 
CDeta[1] := NewHendle(BitW * SizeV1); 
IF CDatat1] © NIL THEN 

BEGIN 


tempH := HHCCData[ 115; 
FOR count := 1 TO BitW * SizeV1 DO 
tempH^^[count] := 0; 


д 
CMap[2].rowBytes := BitW; 
SetRect(CMap[2).bounds, 0, SizeV1, SizeH, SizeV2); 
CDate[2) := NewHandle(BitW * SizeV1); 
IF COata([2] © NIL THEN 
BEGIN 
tempH := HHCCData[21); 
FOR count := 1 TO BitW * SizeV1 DO 
tempH^^[count] := 0; 


END; 
IF (CDatat1] = NIL) OR (CData[2] = NIL) THEN 
N 


EGI 
SetWTitleCCWindow, ‘Not Enough Memmory’); 
DisebleItemCFileMenu, 1); 
END; 
ForeC := 0; 
BeckC := 9; 
DoColor(1, 2); 
InitCursor; 
Done := false; 
END; 


( Standard main program loop that handles all ) 

( events Cie. mouse down, key downs & updates) until ) 
the Done flag is set. ) 

PROCEDURE MainLoop; 
VAR 


tempEvent : EventRecord; 
tempWindow : windowptr; 
tempCode : integer; 
tempPort : Grefptr; 
tempRect : rect; 

BEGIN 

REPEAT 
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SystenTesk ; 
IF GetNextEventCeveryEvent, tempEvent) THEN 
BEGIN 
CASE tempEvent.what OF 
mouseDown : 
BEGIN 
tempCode := FindWindowCtempEvent.where, tempWindow); 
CASE tempCode OF 
inDrag, inContent : 
BEGIN 
IF tempWindow © FrontWindow THEN 
Қайынды ы ыы 


BEGIN 
IF Cwindow = tempWindow THEN 
BEGIN 
IF CWindow € FrontWindow THEN 
SelectWindowCCWIndow) 
ELSE 
BEGIN 
SetRect(tempRect, -25000, -25000, 25000, 25000); 
DragWindow(CWindow, tempEvent.where, tempRect); 


END; 
inMenuBer : 
MainMenuCMenuSelect(CtempEvent . where2); 
inSysWindow : 
SystemClickCtempEvent, tempWindow); 
OTHERWISE 
END; ( of tempCode cese ) 
END; ( of mouseDown 
keydown, autoKey : 
IF BitAnd(tempEvent.modifiers, cmdKey) О 0 THEN 
MainMenuCMenuKeyCCHRCtempEvent .message MOD 256))); 
updateEvt : 
IF CWindow = WindowPtrCtempEvent .message) THEN 
BEGIN 
GetPortCtenpPort); 
Se tPort(CWindow); 
BeginUpdate(CWindow); 
IF CData[1] © NIL THEN 
BEGIN 
HlockCCDataL[ 112; 
CMap[1].baseAddr := CData( 11^; 
CopyBitsCCMap[ 11, CWindow^.portBits, 
CMep[11.bounds, CMap[1].bounds, srcCopy, NIL); 
HUnlock(CDatal 1125; 
END; 
IF CDete(2] © NIL THEN 
EGIN 


I 
HlockCCData[21); 
CMep(21.beseAddr := CData[2]^; 
CopyBitsCCMep[21, CWindow* .portBits, 
CMap[2].bounds, CMap{2].bounds, srcCopy, NIL); 
HUn lock(CDatal2]); 
END; 
EndUpdeteCCWindow); 
SetPortCtempPort); 
END; 
Eres 
END; 
UNTIL Done; 
END; 


(  ***PROGRAM**% ) 
BEGIN 
DoSetup; 
MainLoop; 
END. 
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Advanced Mac'ing 
Pop-Up Pallettes in MPW Pascal 


Pop-Up Pallette Menus 
A New Approach to OverView 


Asa Macintosh developer, I look for ways to make programs 
more responsive and easier to use. Pop-up windows are an 
excellent way to help the user getaccess to information that might 
otherwise clutter the screen or be hidden away and hard to get to. 
However, a number of things get in the way of programming fast 
and painless pop-ups. First, whenever a window comes to the 
top, the window under it is deactivated. That takes time (nota lot, 
but some). Then, when the pop-up window disappears, any 
windows it overlapped must be updated. That can take a lot of 
time (think of MacDraw and lots of objects). Wouldn't it be nice 
to have pop-ups with a truly professional look and feel? This 
article shows you how to implement pop-ups that are fast, 
flexible, and free of side-effects. In addition, for no extra charge, 
you also get a lesson on the Window Manager. 

Anybody who has used a Macintosh is familiar with win- 
dows and how they behave. The Finder provides an excellent 
example of the way windows may be stacked up, with part of their 
contents covered up by other windows. If you click the mouse 
when the cursor is pointing to a go-away box, that window is 
closed. The area previously covered by the window is painted 
white, and everything underneath it is updated. This involves 
drawing the frames and contents of any windows becoming 
visible, as well as repainting the desktop with the background 
pattern. 

Erasing the space a window occupied causes a “flash” of 
white before any windows or their contents are drawn. Drawing 
each windows’ frame, and then the objects within them can take 
quite some time. A few things can be done to improve the way 
this process looks to the user, which is, of course, one of the 
primary goals of having a visual user interface. ІҒ we could 
eliminate the painting and drawing steps, the performance im- 
provement could be astounding. With a technique I call “Those 
Blasted Updates" we can achieve such a goal. Note that the 
methods discussed here are most useful for "temporary" win- 
dows, such as pop-up menus, alerts, or dialogs where some 
windows are being momentarily hidden. However, if you've got 
memory to burn, you can do this with all your windows and 
impress even your Amiga friends (and they have hardware to do 
their magic!). 

Inside the Window Manager 

To appreciate solutions to these problems, one should under- 
stand how and why the Window Manager (WM) operates the 
way it does. If you are already familiar with the WM, you may 
want to skip down to the next section (you can always come back 
and read this stuff later). The WM maintains a linked list of 
windows in use. Each window has a record containing data 
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structures that help to maintain the illusion of front-to-back 
ordering. Some of these are the structure region, content region, 
visible region, and update region. The structure region com- 
pletely encloses the frame of a window. The content region is the 
Structure region minus the window frame. The visible region 
corresponds to the parts of a window that are currently visible, 
except for the window frame. The update region covers the parts 
of a window that need redrawing. The WM modifies these fields 
as windows are moved, resized, selected, or hidden. The visible 
region and update region of a window change shape according to 
which windows (if any) overlap it. The structure region and 
content region are dependent on the size and screen position of 
the window. This discussion will cover what happens when win- 
dows are hidden. 

The WM provides four high level calls that directly or 
indirectly hide a window. CloseWindow removes a window 
from the screen and deletes it from the window list. It also 
releases memory used for data structures associated with the 
window, except the window record. DisposeWindow does the 
same thing, and then discards the window record too. HideW- 
indow simply makes a window invisible. In all three of these 
calls, if the hidden window was the frontmost window, the one 
behind it (if there is one) becomes the front window. The new 
front window is hilighted; if HideWindow is used, the hidden 
window is unhilighted. Hilighting is the WM's way to indicate 
whether or not a window is active. Active windows should be 
different from inactive ones in a distinctive visual way, like 
putting lines in the title bar. The fourth procedure is called 
ShowHide. ShowHide allows you to hide a window without 
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changing the hilighting or the front-to-back order of the windows 
in the list. The WM maintains hilighting consistent with Apple's 
User Interface Guidelines. These guidelines say that the 
frontmost window should be the active window, and that only 
active windows should be hilighted. With the exception of 
ShowHide, these procedures generate activate events that di- 
rectly correspond to hilighting and unhilighting. Activate events 
are signals to an application that windows are becoming active or 
inactive. Applications should take appropriate actions, such as 
activating or de-activating controls or selected text. 
Gory Details 

Part of hiding a window involves changing its data struc- 
tures. A hidden window has no use for a visible region, structure 
region, content region, or update region. The WM makes these 
regions empty. The window is marked as invisible and unhil- 
ighted, with the exception of ShowHide as noted above. After 
a window's data structures have been changed, the screen must be 
updated to reflect the absence of a window. As mentioned earlier, 
the place on the screen previously occupied by the window is 
painted white. This is done to make further updates look cleaner. 
If an application chooses not to redraw the contents of a newly 
visible window, white space will remain instead of garbage left 
over from the other window. Since the visible region of any 
window is dependent upon other windows above, all windows 
under the hidden one must have their visible regions recalculated. 
All the portions of each window that are becoming visible are 
collected into the window's update region. 


Where Update Events Come From 

If, after these calculations are performed, a window has a 
non-empty update region, an update event will be generated for 
that window. Update events are the WM's way of telling an ap- 
plication that previously hidden areas must be redrawn. An 
application's usual response to an update event is to call a routine 
that will draw the pieces necessary torefresh the screen. The WM 
provides two procedures to guarantee that a window's update 
region won't cause more than one update event. The first is 
BeginUpdate. This procedure saves the current visible region 
and sets it equal to the update region. The update region is 
emptied. This results in QuickDraw operations being “clipped” 
to the visible areas that need refreshing. The second routine is 
EndUpdate. It restores the visible region of the window so that 
subsequent drawing procedures can use the whole visible area of 
the window. 

These actions that the WM normally performs take a rela- 
tively long time to complete, especially if large regions and many 
windows are involved. The paint-first-then-draw rule serves to 
lengthen the user's perception of the time needed to update the 
screen. Any user of MacDraw knows how long it can take to 
redraw many complex objects in response to update events. 

So, now what? 

Some actions normally taken by the WM can be more 
effectively performed by the application. To do this, we are 
going to teach windows to disappear gracefully. The WM 
normally draws the window frames and expects the application 
toredraw the contents in response to update events. By not using 
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calls to the WM (and skipping the frame drawing and content 
drawing), the perceived performance of window hiding opera- 
tions is greatly enhanced. The paint-first-then-draw sequence 
can be completely circumvented by not calling ShowHide or 
HideWindow. Instead, the application can execute equivalent 
operations on its own. First, itshould empty out the disappearing 
window's visible region, structure region, content region, and 
update region. Next, it should mark the window invisible. If the 
window was hilighted it should be unhilighted. This is the point 
where the WM would normally paint the disappearing area 
white. We are not going to do that, because it makes things look 
slower. The last step is to force the recalculation of the visible 
regions of each window that was covered up by the disappearing 
window. This is done with a low-level WM procedure called 
CalcVisBehind. 

CalcVisBehind takes two parameters, a window pointer 
and a region handle. It starts with the window it is passed, and 
calculates the visible regions of all windows downward in the 
window list that intersect the region. Since the area requiring 
recalculation corresponds to the hidden window's structure re- 
gion, that region should be copied before it is emptied, so it can 
be passed to CalcVisBehind. The window pointer should be the 
one returned by FrontWindow, another WM call. FrontWin- 
dow returns the first visible window in the list, so it will return 
the window immediately underneath the hidden one. With the 
exception of not painting white, this process is essentially the 
same as ShowHide, since it doesn't worry about the hilighting of 
any windows underneath the hidden one. 

The two goals of this approach, no window drawing and no 
content drawing, are also the two major problems. The applica- 
tion isn't ever told explicitly to update the contents of its win- 
dows. Also, the WM isn't allowed to redraw the frames of newly 
visible windows. So, who's in charge of updating the screen? 
(No, who's on first...) Since the application is bypassing the WM, 
itmust take full responsibility for updates as well. Recall that this 
discussion is concerned mainly with “temporary” windows such 
as pop-up menus or dialogs, so keeping track of updates is kept 
relatively simple. Since we won't allow traditional updating to 
occur, we need to remember what was on the screen before the 
pop-up obliterates it. Before a window is popped up, the 
application should copy the part of the screen that will be covered 
up. This can be done by maintaining an off-screen bitmap. The 
window can then be placed on the screen and its contents drawn. 
After the window is marked as invisible, the screen can be 
restored by copying the temporary bitmap back where it belongs. 
This provides very fast updating when a window is hidden, much 
faster than conventional methods. It looks especially nice since 
the “flash” doesn't happen. 

“My kingdom for a good example...” 

Instead of providing a contrived example showing these 
techniques, I'm going to offer some changes to an existing piece 
of code. Scott Boyd's OverView [“OverView, Getting the Big 
Picture”, MacTutor, Sept. 1986] contains some excellent code 
for maintaining off-screen bitmaps and providing pop-up win- 
dows. OverView is a pop-up control that shows the user a 
compressed view of large documents. In the sample program 
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Scott provides, OverView is summoned by holding the mouse 
button down while the cursor is the content region of a window. 
The OverView window pops up andallows the user to change the 
location of the viewport on the document (like MacPaint's 
ShowPage feature). When the user lets go of the button, 
OverView disappears. The prevention of update events was 
important to the success of OverView. Just before OverView 
pops up, the pixels underneath it are saved off-screen. OverView 
is hidden by calling ShowHide. After it disappears, the pixels are 
copied back onto the screen. The update event for the window 
underneath is "stolen" by performing BeginUpdate and EndUp- 
date calls. Activate events are avoided by using ShowHide 
instead of ShowWindow and HideWindow. 


There are some drawbacks with OverView using these 
methods. Without traversing the window list, OverView can 
only know about the window immediately underneath it. Asa 
result, the OverView window must fit entirely inside the struc- 
ture region of that window so that it will not eclipse any other 
windows. Also, stealing the update region of a window can have 
unpredictable results. The WM procedures used will empty the 
entire region, including any parts not caused by OverView. This 
could result in places not getting updated if the OverView 
window is popped up when the front window has a non-empty 
update region (as mentioned in his article). ShowHide has the 
side effect of providing that irritating flash of white before the 
pixels are copied back into place. 


With a few changes to the OverView UNIT, the imposed 
restrictions can be eliminated. The ShowHide call can be 
replaced by a few statements that perform the same actions, but 
without the side effects. The two ShowHide calls in 
OV HandleSelection can be replaced by the following: 


( declare this local to OV HandleSelection ) 
clobberedRgn := NewRgn; 
{ We'll need this later, to know where the OV window was 


CopyRgn( WindowPeek(OV)^.strucRgn, clobberedRgn ); 


{ mark the window invisible, and empty the regions } 
WindowPeek(OV)^.visible := false; 
SetEmptyRgn(WindowPeek(OV)^.strucRgn); 
SetEmptyRgn(WindowPeek(OV)^.contRgn); 
SetEmptyRgn(OV^.visRgn); 


( calculate the visRgns of all windows under hidden one } 
CalcVisBehind(WindowPeek(FrontWindow), clobbere- 
dRgn); 


{ get rid of it, we don't need it anymore! ) 
DisposeRgn(clobberedRgn); 


Take out the BeginUpdate and EndUpdate calls that come 
after the second ShowHide call. They aren't necessary because 
the WM isn't being allowed to create any update regions. Since 
the WM isn't generating any update events, the OverView 
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window can be allowed to go anywhere on the screen. Itcan even 
be popped-up while there are outstanding update events for other 
windows. OverView puts everything back just the way it was, 
and doesn't even leave any footprints in the butter. The "flash" 
problem is alleviated by not calling ShowHide. The pixels are 
replaced right on top of OverView; no erasing is necessary. 
Many of you eagle-eyed Macintosh users realize that menus 
work this way. That is, a menu that pops back up isn't erased 
before the screen is restored to normal. 


There are a few other changes to the OverView UNIT that 
don't really involve speed improvements and such, but they are 
valuable additions to this user interface innovation. These 
changes came about while writing a sample application to show 
off the speed enhancements. Right now, OverView always 
makes the same kind of pop-up window. Other kinds of windows 
can be allowed by adding a parameter to NewOverView (the 
procedure that creates a new OverView window). Change the 
procedure header to: 


Procedure NewOverView( 
var OV : WindowPtr; 
viewRect : Rect; 
factor : Real; 
whatKind : Integer ); 


var OV pagePict : Bitmap; 


The whatKind variable can contain one of the WM's known 
window kinds. Replace altDBoxProc in the NewWindow call 
with whatKind. This change is purely cosmetic, but that's what 
much Mac programming is about, right? Since OverView was 
created to make “random access scrolling" available for large 
documents, it expects two scroll bar handles to be passed to 
SelectOver View. But applications like MacWrite don't have 
two scroll bars on documents. With two changes to 
OV HandleSelection, nil may be passed if a scroll bar isn't being 
used. Change the two SetCtlValue statements as follows: 


if HScrollBar «» nil 

then SetCtiValue( HScrollBar, tempPt.h ); 
if VScrollBar <> nil 

then SetCtiValue( VScrollBar, tempPt.v ); 


This allows a programmer to create applications that don't 
useany scroll bars, yet still have documents larger than the screen 
will show all at once. Speaking of scroll bars and scroll positions, 
another minor change in the code can bring about a change in the 
screen location of the pop-up. Right now, the pop-up window 
appears with its upper left corner at the cursor position, except 
when it has to be moved to fit completely on the screen. Apple's 
Human Interface Group suggested that the window should ap- 
pear with the current scroll position under the cursor, but it was 
really Steve Knouse’s constant nagging that motivated me to 
change it. Since the scroll position is passed as a parameter to 
Over ViewSelect, a simple offset can be performed to do this. 
Replace offset := where; at the beginning of 
OV_PositionOver View with the following: 
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{ тар the seroll position into the pop-up ) 
tempPt := scrollPosition; 
MapPt( tempPt, viewRect, OV^.portRect ); 


offset :z where; 


{ let's offset the corner of the pop-up 
by the amount of the scroll position, 
but in the opposite direction ) 

offset.h := offset.h - tempPt.h; 

offset.v := offset.v - tempPt.v; 


Going Where No OverView Has Gone Before 

With these few changes, it is possible to use OverView for 
apurpose that was never intended. Since scroll bars are no longer 
assumed to exist, the modified UNIT may be used for Pal- 
etteSample is a relatively simple application that illustrates both 
the speed and the versatility of the modified OverView UNIT. As 
the name suggests, PaletteSample makes use of a palette to show 
off OverView. The palette contains all the patterns familiar to 
MacPaint users, but it is not always visible like the one in 
MacPaint. It pops up only when it's necessary to select a new 
pattern. All of the code for handling the pop-up palette is in a 
UNIT called UPalette. UPalette has two “public” procedures, 
InitPatternPalette and PatternSelect. InitPatternPalette 
builds the pattern palette, makes a new OverView window (via 
NewOver View), and updates the bitmap for the new OverView 
window by calling UpdateOverView. 

PatternSelect is used by the main program to select a new 
pattern. It calculates a scroll position based on the pattern 
number passed it, and calls Over ViewSelect to make a new 
pattern selection. The calculations for the scroll position are 
dependent on the shape of the palette, discussed later. The term 
"scroll position" is misleading because scrolling a document is 
not the purpose of the pattern palette. However, OverView 
performs its operations with scrolling in mind, so it's convenient 
to use "scroll position" when we really mean "pop-up position". 
OverView inverts a rectangle on the pop-up window that repre- 
sents the view in the document window. The inverted rectangle 
tends to disturb the appearance of the palette, so another change 
to OverView is necessary. An additional parameter to Over- 
ViewSelect lets the programmer decide whether or not to invert 
the current selection: 

Procedure OverViewSelect( where: Point; 

viewRect : Rect; VAR scrollPosition : Point; 
VAR OV : WindowPtr; VAR OV pagePict : bitMap; 


HScrollBar, VScrollBar : ControlHandle; 
invertSelection: boolean); 


Change the InvertRect call in OV ShowOverView to 
if invertSelection then InvertRect( scope ); 


Change the InvertRect and OV FlashSelection calls in 
OV HandleSelection to 
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if invertSelection then 
begin 
InvertRect( scope ); 
OV FlashSelection; 
end; 


OverView returns an updated scroll position, and Pattern- 
Select calculates which pattern was under the cursor. This 
calculation is also based on the shape of the palette. UPalette 
provides a palette that has 8 patterns across and 5 patterns down. 
The patterns are put down in order by rows, so that the 9th pattern 
is the first one in the second row, etc... Since the system pattern 
list has 38 patterns, the last two spots on the palette are left empty. 
PatternSelect returns the ID# of the newly chosen pattern (if 
there was one) in the patternNumber parameter. 

The main program contains an event loop, some code to 
handle creating, moving, and resizing windows, as well as 
menus. Each window, created by selecting New Window in 
the File Menu, has an oval in it. The oval in each window can 
have a different pattern, which can be changed using the pop-up 
pattern palette. The user is allowed to create as many windows 
as they want, and each one can be moved, resized, or put away. 
After some boring initialization code, the program calls InitPat- 
ternPalette to get the ball rolling. At this point it drops into the 
main event loop, where it handles mouseDown, activate, and 
update events. If a mouseDown event occurs inside the content 
region of any window, the pop-up palette is used to select a new 
pattern for the oval in that window. The windows behave as 
Macintosh users have come to expect. As windows are moved, 
resized, or put away the WM generates update events that are 
handled by redrawing the ovals in updated windows. 

There's always a catch 

The scrolling nature of OverView causes a few anomalies in 
non-scrolling applications. The need to maintain a “scroll 
position" has already been mentioned. A related problem occurs 
when the user is selecting a pattern. As the user drags the cursor 
around over the palette, a little gray box follows it around. This 
gray box is the same size as the inverted rectangle mentioned 
above. It's there to show the user how much of the document will 
be visible in the document window after scrolling takes place. 
Without more drastic changes to OverView, this feature cannot 
be eliminated. 

Speaking of drastic changes, Scott and I have quite a few of 
them planned for OverView. Weare planning to transform it into 
a more general "Pop-up Manager". The new manager will be 
able to do many "standard" forms of pop-up devices such as 
menus, palettes and, of course, document viewing tools. Menus 
and palettes will be implemented using the List Manager. All of 
the standard pop-ups will use action procedures to perform their 
activities. Programmers will be able to provide their own action 
procedures to enhance existing operations, or to provide com- 
pletely new ones. We've also got plans to transform the new 
manager into an object for use with MacApp. When it's finished, 
well place it in the object library being maintained for the 
MacApp Developer's Association by Kurt Schmucker. 

By the way, all you MacApp fans out there should join 
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MADA as soon as you can. Contact Carl Nelson, P.O Box 23, ebout using CalcVisRgn to prevent 


Everett WA, 98206. — updete events when hiding the 
Wrapping things up gbm 10/31/86 - Changed OV_HandleSelection to only | 
This article assumes a couple of things about pop-up win- Inval where the OV window was if 


there 


dows. First, they appear on top of everything else. Second, 
nothing unusual happens underneath them while they are up. (i.e. not 

That is, no drawing or other shenanigans will be going on outside scrolling а document) 

the pop-up window. Anything updated in a window other than ) 

the pop-up might be obscured by the pop-up. When the pop-up | (------------------------------------------------------------- 
disappears and the pixels are replaced, the “old” informationmay | -------------} 

not match the "new" information. Thats why the methods ИШЕНГИС 

discussed here are probably best for “temporary” windows. Of | (Compiler Switch Settings) 

course, by managing some bitmaps here and there, somebody Rt 

could extend these techniques to all windows. A 128K Macin- ($0v*) 

tosh probably wouldn't be a great place to try it, but Macintosh | uses ($U MemTypes.p ) MenTypes, 


were no scroll bars involved 


Pluses (and beyond) will have plenty of memory to do this. All ($0 QuickDrew.p ) ^ QuickDrew, 
: ata А , ($0 OsIntf .p ) OsIntf, 

you need to do is maintain an off-screen copy of each windows ($U ToolIntf.p ) ToolIntf 

contents. Drawing operations into these duplicate grafPorts can ($U SANE.p ) SANE; | 


occur during idle time (between mouse clicks or keydown 


. e А const 


done by "blasting" bitmaps instead of the dreaded paint-first- TitleBarHeight = 18; (Height of window title bar ) 
then-draw technique. Yea, I know it's a pain to keep track of all 2. ж E ( 221 xi "sef т ) 
А ‚ arHeig = ; (Height of scro er 
applications is tremendous. 
I'd like to thank the Academy... procedure NewOverViewC var OV.pagePict : bitMap; 
I want to express my gratitude to a number of people, without а ақш 
whom this article would have never made it to press. Scott Boyd, fector : Real; f 
of OverView fame, provided invaluable assistance in the crea- whatKind : Integer); 


tion and development of most the ideas presented in this article. 
He was almost always available to discuss new ideas, to “ип- 
stuck" me, or to correct my spelling. I guess the fact that he's my 
roommate kind of helped with the availability part. Thank you | Procedure OverViewSelect( where: Point; 


procedure UpdateOverView( Procedure drewProc; 
OV_pagePict : bitMap); 


à е viewRect : Весі; VAR scrollPosition : Point; 
to Andrew Donoho, the author of MacSpin"* , who manages his VAR QV : WindowPtr; VAR OV_pagePict : bitMap; 
pop-ups the way I've described here. He had the idea first and HScrollBar,VScrollBer : ControlHandle; 
challenged me and Scott to figure out how he did it. Well, invertSelection: boolean); 


Andrew, here it is. Thanks also to Steve Knouse of Apple | 


Computer, the original (and hopefully only) TechnoStud. And, | IMPLEMENTATION 
finally, thanks to David Smith and crew for giving us such a | Procedure NewOverView С var OV-pegePict : bitMap; 


М А В ver OV : WindowPtr; 
unique place to air our ideas. viewRect : Rect; 


factor : Real; 
< OverView source > whatKind : Integer ); 


var 
< UPalette source > dummyRect : Rect; 


< PaletteSample source > horizontal, ( horiz. pixel size of the OV window ) 
Ls rr vertical : Extended; ( vert. pixel size of the OV window ) 
UNIT OverView; sizeO0fOff : Size; ( bytes needed for offscreen bitmap ) 
(Version 1.0 July 12, 1986 9:47:53 PM offRowBytes : Integer; ( bytes for offscreen bitmap ) 


by Scott T. Boyd, the MacHax™ Group bitRect : Rect; (size of OV window and bitmap) 
dummy : Point; 
(Version 1.1 December 16, 1986 11:21:16 PM offPort, ( temporery working port ) 
by Greg Marriott of SoftWare To Go, oldPort : GrafPtr; ( temporary storage ) 
also a member of the MacHax™ Group) begin 
( compute available vertical screen space ) 
Hatchet history: | vertical := ScreenBits.bounds.botton - 
gbm 9/26/86 - Added parameter to NewOverView for ScreenBits.bounds.top - MenuBarHeight; 
windowKind | vertical := vertical * factor; 
gbm 9/26/86 - Added check to see if scroll bar handles 
ere nil in OV_HandleSe lection; if ( compute horizontal proportion ) 
they ere, | ‚ horizontal := vertical * viewRect.right / 
don't try to set 'em viewRect .bottom; 


gbm 10/1/86 - Finally figured out what Andrew meant 
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+1: 


( create the new window record } 

SetRectC dummyRect, 0, 0, Num2Integer( horizontal ), 
Num2 Integer ¢ vertical ) ); 

OV := NewWindow( nil, dunnyRect, ‘* , FALSE, 
whatK ind, WindowPtrC -1 ), FALSE, Longint¢ 02); 


( create offscreen bitmap ) 
bitRect := OV*.portRect; 
of fRowBytes := ( ( bitRect.right - bitRect.left ) div 8 ) 


if OddC offRowBytes ) then 
offRowBytes := offRowBytes - 1; 
sizeOfOff := С bitRect.bottom - bitRect.top ) * 
of fRowBytes; 
with OV.pagePict do 
begin 
baseAddr := QDPtr( NewPtrC sizeOfOff ) ); 
rowBytes := of fRowBytes; 
bounds := bitRect; 
end; 


( fill the bitmap with white ) 

GetPortC oldPort ); 

offPort := GrefPtrC NewPtrC sizeofC GrafPort ) 2 2; 
OpenPort( offPort 2; 

SetPortBitsC OV.pagePict ); 

FillRectC bitRect, white 2; 

SetPortC oldPort ); 

ClosePortC offPort ); 

DisposPtr¢ Ріг offPort 3-3; 


end; ( MekeOverView ) 


procedure UpdeteOverViewC Procedure drawProc; 


OV_pagePict : bitMap); 
ver 
of fPort, 
oldPort : GrefPtr; 
begin 


end; 


GetPortC oldPort ); 
offPort := GrefPtrC NewPtrC sizeofC GrafPort ) ) ); 
OpenPort( offPort ); 


( make 811 drawing happen offscreen ) 
SetPortBitsC OV_pagePict ); 
drawProc; ( let the caller drew his stuff ) 
SetPortC oldPort ); 
ClosePort( offPort ); 
DisposPtrC Ріг( offPort 3-35 
( UpdateOverView ) 


( return drewing to normal ) 


procedure OverViewSelect( where: Point; 


ver 


viewRect : Rect; VAR scrollPosition : Point; 

VAR OV : WindowPtr; VAR OV_pagePict : bitMap; 

HScrollBar,VScrollBer : ControlHandle; 
invertSelection: boolean); 


MenuF lash : “Integer; ( system global ) 

value, ( value returned by TrackGrayRgn ) 

h,v : LongInt; 

pene, ( the size of the “drawable” area ) 

tempPt : Point; (в temporary point (duh!) ) 

Scope, ( size of pene scaled into OV window ) 

tenpRect, 

linitRect, ( linit for drag region ) 

slopRect, ( slopiness allowance for dregging ) 

structRect : Rect; (for strucRgn of OV window ) 
280 


bitmap) 


dragRectRgn 
oldPort 
theWindow 
underScope 


: RgnHandle; ( region the user drags ) 
: GrafPtr; 
: WindowPtr; ( holds the frontWindow ) 
: BitMep; ( dynamically allocated 
offscreen 


whichWindow : WindowPtr; ( for save & restore bits) 
clobberedRgn, 


visIntersectRgn : RgnHandle; 


----------------------------------) 


procedure OV. Ргераге; 


begin 
MenuF lash := pointer($A24); 
GetPortC oldPort ); 
theWindow := FrontWindow; ( active window ) 
BringToFrontC OV ); 
SetPort( OV 5; ( it's now the current port } 
ShowHideC OV, "FALSE ); (it's also not visible ) 
MoveW indow( OV, 8,8, FALSE ); (home the window) 


(compute the size of the current window pane) 

pene.h := theWindow^.portRect.right - theWindow^ 
.portRect.left - sBarWidth; 

pene.v := theWindow^.portRect.bottom - theWindow^ 
portRect.top - sBarHeight; 


( Scale the pane into the OV window to show size 
relative to document) 

SetRect( tempRect, 0, 0, pane.h, pane.v ); 

MapRect( tempRect, viewRect, OV*.portRect ); 

scope := tempRect; 


(make the scope region to drag around. ) 
dragRectRgn := NewRgn; 
RectRgnC dragRectRgn, scope ); 


( this works to limit the movement of dragRectRgn ) 

SetRect( limitRect, 0, 0, OV*.portRect.right - 
scope .right +1, бү .portRect. bottom - 
Scope.bottom + 1 ); 


(scale scrollPosition into OV ) 

tempPt := scrollPosition; 

MepPtC tempPt, viewRect, OV^.portRect 2; 

OffSetRect( scope, tenpPt. h, tempPt.v ); 
end; ( OV.Prepere ) 


нал ина дыы RE 
procedure 0V.PositionOverView; 
ver 
offset : Point; 
begin 


SetPortC oldPort ); 


tempPt := scrollPosition; 
MapPt( tempPt, viewRect, OV^.portRect 2; 


offset := where; 

offset.h := offset.h - tempPt.h; 

offset.v := offset.v - tempPt.v; 

GlobalToLocal € offset ); 

h := offset.h; ( this is the value of the mousedown 
v :* offset.v; 

( be sure it doesn't go off the bottom of the screen 


if Су + 0V^.portRect.bottom) >= 
thePor t^ .portBits.bounds .bottom 


у := thePort* .portBits.bounds bottom - 
0V* .portRect.bottom - 1; 


( make sure it doesn't go off the right of the 
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Screen ) 


then 


end; 
proce 
ver 


if Ch + 0V* .portRect.right) >= 
thePor t^ .portBits.bounds .right 


h := thePort^ .portBits.bounds.right - 
0V*.portRect.right - 1; 


( meke sure it doesn't go off the top of the screen 


if v < thePort^.portBits.bounds. top 
then v := thePort*.portBits.bounds. top; 


{ make sure it doesn't go off the left of the screen 


if h < thePort* .portBits.bounds. left 
then h := thePort*.portBits.bounds. left; 


SetPt ( offset, h, v); 
LocalToGlobal( offset ); 
h := offset.h; 

offset.v; 


v 


SetPort(C OV 2; 
MoveWindowC OV, h, v, FALSE 2; 
( 0V-PositionOverView ) 


------------------------------) 


dure OV. SeveBits; 


sizeOfOff : Size; ( for bitmap size calculation ) 
offRowBytes : Integer; ( ditto } 

underRect, 

bitRect : Rect; ( these are as big as the OV window 


of fPort, 


begin 


oldPort : GrafPtr; ( temporary storage ) 


GetPort( oldPort ); 


( put the window mageger port into offport ) 
GetWMgrPortC offPort 2; 
whichWindow := WindowPtr( offPort 2; 


(allocate a new grefport) 
offPort := GrefPtrC NewPtr( sizeofC GrafPort ) ) 2; 


( home а copy of the bounds of the OV window) 
bitRect := 0V^.portBits.bounds; 
offsetRect( bitRect, -bitrect.left, -bitrect.top 2; 


( compute memory necessary for offscreen bitmap ) 
{allocate it and setup bitmap record) 
offRowBytes := С bitRect.right div 8 ) + 1; 
if OddC offRowBytes ) then 
offRowBytes := of fRowBytes -1; 
sizeOfOff := bitRect.bottom * of fRowBytes; 
with underScope do 
begin 
beseAddr := QDPtrC NewPtr( sizeOfOff ) ); 
rowbytes := offRowBytes; 
bounds := bitRect; ( using HOMEd rectangle ) 
end; 


( move underRect to where OV will eppeer ) 
underRect := underScope .bounds; 
OffsetRectC underRect, h-1, v-1 2; 


( actually save the bits ) 

OpenPortC offPort ); 

SetPortBits( underScope 2; 

SetClipC offPort^.visRgn 2; 

CopyBitsC whichWindow^.portBits, underScope, 
underRect, underScope.bounds, srcCopy, NIL ); 

SetPortC oldPort 2; 

ClosePort( offPort 2; 
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end; 


DisposPtr( PtrC offPort ) ); 
( OV_SaveBits ) 


procedure OV_ShowOver View; 


begi 


end; 


n 
OV_SaveBits; 
ShowHideC OV, TRUE ); ( the window appears! ) 


( blast miniature picture into OV ) 


CopyBitsCOV_pagePict, OV* .portBits, 
OV_pagePict.bounds, OV*.portRect, 
srcCopy, nil); 


( highlight the current selection ) 
if invertSelection then InvertRect( scope ); 


( give the user some room to be sloppy ) 
slopRect := OV*.portRect; 
InsetRect( slopRect, -25, -25 ); 


GlobalToLocal( where ); 


( compute size of the draggable region and center it 
on the cursor } 

boxWidth := scope.right - scope. left; 

boxHeight := scope.bottom - scope. top; 

OffsetRgnC dragRectRgn, where.h - CboxWidth div 2), 
where.v - CboxHeight div 2) ); 

OffSetRectC limitRect, boxWidth div 2, boxHeight 
div 2); 


( let the user drag it around ) 

value := DragGrayRgn( dragRectRgn, where, 
limitRect, slopRect, 8, nil ); 

( 0V-ShowOverView ) 


procedure OV_RestoreBits; 


ver 


underRect: Rect; 


begin 


end; 


underRect := underScope.bounds; 


( home the rectangle ) 
OffsetRectC underRect, -underRect. left, 
-underRect.top ); 


{ position it correctly } 
OffSetRectC underRect, h-1, v-1 ); 


CopyBitsC underScope, whichWindow^.portBits, 
underScope.bounds, underRect, srcCopy, NIL); 

( deallocate the bitmap space (be nice and clean) ) 

DisposPtrC PtrC underScope.baseAddr ) ); 

( OV_RestoreBits ) 


procedure OV. HandleSelection; 


begin 


procedure OV_F lashSelection; 
var 
i: Integer; 
j: LongInt; 
begin 
HLockC HandleC dragRectRgn ) ); 
for i := 1 to 2*MenuFlesh^ do 
begin 
InvertRectC dregRectRgn^^.rgnBBox 2; 
DelayC 4, j 5; 
end; 
HUnLockC HandleC dregRectRgn 22; 
end; 


------------------------) 
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if € HiWordC value 20-32768) ог 
С LoWordC value )<>-32768) 
then ( user actually mede a selection ) 
begin 
if invertSelection then 
begin 
InvertRect( scope 2; ( turn off current 


selection ) 


event ) 


then 


else 
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0V.FlashSelection; 
end; 


( hide the window ) 
WindowPeekC OV 2^.visible := false; 


( remember where the OV window is on screen } 

visIntersectRgn := NewRgn; 

RectRgn( visIntersectRgn, windowPeek( OV 27. 
strucRgn** .rgnBBox ); 


{empty his regions...) 

SetEnptyRgnC WindowPeekC OV )*.strucRgn 2; 
SetEmptyRgn( WindowPeek( OV )*.contRgn 2; 
SetEmptyRgn( OV*.visRgn 2; 


( make sure to pretty up the other windows ) 

CalcVisBehind( WindowPeekC theWindow ), 
visIntersectRgn ); 

DisposeRgn(visIntersectRgn); 


SetPortC oldPort ); 
OV.RestoreBits; ( blast bits back into place ) 


( figure the new scrollPosition } 

SetPtC tempPt, dragRectRgn**.rgnBBox. left, 
dregRectRgn^^.rgnBBox.top ); 

MepPtC tempPt, OV^.portRect, viewRect ); 

scrollPosition := tempPt; 


( prepere to set new control values ) 
tempRect := viewRect; 

tempRect.bottom := tempRect bottom - pane.v; 
tempRect.right := tempRect.right - pane.h; 
MapPt С tempPt, tempRect, viewRect 2; 


( set the new scroll ber values ) 
if HScrollBar © nil then 

SetCtlVelueC HScrollBar, tempPt.h ); 
if VScrollBar € nil then 

SetCtlValueC VScrollBar, tempPt.v ); 


( if you're really scrolling, force en update 
if € VScrollBer © nil ) or С HScrollBer nil ) 


InvelRectC theWindow^.portRect ); 
end 
(no selection was mede) 
begin 
( hide the window and meke it quick! ) 
WindowPeekC OV 2^.visible := false; 


( remember where the OV window is on screen ) 
visIntersectRgn := NewRgn; 
RectRgn( visIntersectRgn, windowPeek( 

OV )*.strucRgn** .rgnBBox ); 


(empty his regions...) 

SetEnptyRgnC WindowPeekC OV 2^.strucRgn 2; 
SetEnptyRgnC WindowPeek( OV )^.contRgn 2; 
SetEmptyRgnC OV*.visRgn 2; 


( make sure to pretty up the other windows ) 
CalcVisBehind( WindowPeek( theWindow ), 
visIntersectRgn 2; 


DisposeRgn(visIntersectRgn); 


SetPortC oldPort ); 
OV_RestoreBits; ( replace the underneath bits ) 


end; 
end; ( OV.HandleSelection ) 
procedure OV_TidyUp; 
begin 
DisposeRgn( dragRectRgn 2; 
rds ( OV_TidyUp ) 


Шалы DS iiie нола PC E ) 
begin 
0V.Prepere; 
OV_PositionOver View; 
OV_Show0verView; 
OV_HandleSelection; 
OV_T idyUp ; 
end; ( OverViewSelect ) 


END. ( UNIT OverView ) 


UNIT UPalette; 
(Popup Palette UNIT 
Version 1.0 Scott T. Boyd & Greg B. Marriott 
Copyright 1986 by the MacHax(tm) Group 
P.0. Box 5678 
Aggieland, TX 77844 
(409) 846-4102 
All rights reserved. 


We hereby license you to use this code in any way you went. 
If you do use this code in а program, you will receive а 
license to distribute it when we receive a copy of what you 
intend to distribute. 


If you get rich with it, you ere certainly welcome to send us 
some money. 


Just in cese the courts really do decide that а visual feel 
is protected under current copyright and patent laws, we 
thought of this idea first and claim that we deserve to get 
filthy rich if you make a mint using the concept of the pop- 
up, two-dimensional, random access [scroll bar) menu. 


rion, October 3, 1986 8:03:39 PM 


INTERFACE 


7” Switch Settings) 
($Е+ (renge checking on) 
($0V*) (overflow checking on) 


uses ($U x ) MenTypes, 
($U QuickDraw.p ) QuickDrew, 
($0 OsIntf.p — ) OsIntf, 
($U ToolIntf.p ) ToolIntf , 
($U OverView.p) OverView; 
ver 
patternPopUp : windowPtr; ( for the OV window ) 
viewRect : Rect; ( the most current size ) 
nyB i tMap : BitMap; ( for the offscreen palette) 
i sysPat terns : PatHendle; ( standard pattern list 
popupViewRect : Rect; ( size of actual palette ) 


bigpatternPICT : PicHendle; ( the palette itself ) 


procedure PatternSelect( ver patternNumber: integer; 

where: 
point); 
( On entry, patternNumber points to the current pattern. 
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Valid numbers are 1..38 in the system pattern list.) 


procedure InitPatternPalette; 


(есе ез ана дыны ны аншы анына шаны ы ынша ) 
IMPLEMENTATION 
procedure PatternSelect( var patternNumber: integer; 
where: 
point); 
var 
scrollPosition, ( these are needed by OverView ) 


oldScrollPosition: Point; 
row, column: longint; ( for calculation of scroll position 


E : Point; ( ditto ) 


function WhichPattern(scrPosition:point): integer; 
( this returns a pattern number based on а scroll 
position ) 
var 
petternPt : Point; 
windowSize : Point; 
thePattern: integer ; 
begin 
( windowSize is just what it says ) 
windowSize.h := thePort^.portRect.right - thePort* 
.portRect . left; 
windowSize.v := thePort^.portRect.bottom -thePort^ 
.portRect . top; 


( this little calculation is needed because the scroll 
position reflects the upper left corner of 
OverView’s 
viewRect, while the cursor is in the center of the 
viewRect } 
patternPt.h := scrPosition.h + windowSize.h div 2; 
patternPt.v := scrPosition.v + windowSize.v div 2; 


( this calculation is based on the shape of the 
pelette: 
8 by 5 petterns. Each pattern is boxSize big. ) 
thePattern := (patternPt.h div boxSize.h) + 
CpatternPt.v div 
boxSize.v)*8 + 1; 


whichPattern:=thePattern; 
ШЕ ( WhichPattern ) 


begin 
boxSize.h := viewRect.right div 8; ( 8 across ) 
boxSize.v := viewRect.bottom div 5; ( 5 down ) 


( figure out the scroll position for the pattern number 
currently selected. The 'boxSize div 2^ in each 
assignment is to make the center of the pattern 
box the scroll position, not the upper left corner. ) 
row := boxSize.h * (CpatternNumber - 1) mod 8) + 
(boxSize.h div 2); 

column := boxSize.v * CCpatternNumber - 1) div 8) + 
(бохбіге.у div 2); 

SetPtC scrollPosition, row, column 2; 


( we’ll need this to detect a change ) 
oldScrollPosition := scrollPosition; 


( invoke OverView to pick a pattern ) 
OverViewSelect(where, viewRect,scrollPosition, 
patternPopUp, myBitMap, nil, nil, false ); 


if not EqualPtColdScrollPosition,scrollPosition) 

then begin (а new selection was made) 
( now let's figure out which pattern they are in ) 
patternNumber := whichPattern(scrollPosition); 
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end; 
үші ( PatternSelect ) 


Procedure DrawPoop; 

( This is called by OverView to make the offscreen bitmap for 
the pop-up. ) 

begin 
DrewPictureCbigPatternPICT, popUpViewRect); 


procedure MakePalette; 

( Guess what? This procedure mekes the palette. ) 

var 
aRect: Rect; ( roving rect to be filled ) 
i,j,k: integer; ( just for the taste of it... } 
thePattern: Pattern; ( pattern to fill with ) 
oldClip: RgnHandle; 

begin 


( let’s make sure the clip region is big enough ) 
oldClip:-zNewRgn; 

GetClipColdClip); 
SetRectCeRect, - 10000, - 10000, 10000, 10000 ); 
ClipRectCaRect); 


( start recording a picture, and get to work ) 
bigPatternPICT:=OpenPicture(viewRect); 
PenPat(black); 


for i:=1 to 5 do ( the rows in the pattern palette } 
begin 
( calculate the position of the rectangle ) 
SetRectCaRect, 0, 400* C i- 12, 400, 400*i ); 
for j := 1 to 8 do ( the column elements ) 
begin 
( calculate a pattern number from row,column ) 
k := (1-1)%8 + j; 


( make sure there's really a pattern with this ID! 


) 
if k « 39 
then begin 
( get the pattern, shrink the rect (for a 
little 
white space), fill it up, grow it back 
egain, 


end offset it to the next position ) 
GetIndPatternCthePattern, sysPatListID, k); 
InsetRectCaRect, 30,30); 
FillRectCeRect, thePattern); 
InsetRectCeRect, -30, -30); 
Of fsetRectCaRect , 400,0); 
end; 
end; 
end; 


( finish up the picture, and restore the clip ) 
ClosePicture; 
SetClipColdClip); 
DisposeRgn(oldClip); 
re { MakePalette } 


procedure InitPatternPalette; 
( call this procedure to kickstart the palette ) 
ver 
paletteFactor : real; 
begin 
( set the virtual size of the pop-up (viewRect) 
and the actual size of the pop-up C(poupViewRect) ) 
SetRect С viewRect, 0, 0, 3200, 2000 ); 
SetRect € popupViewRect, Ø, Ø, 160, 100 ); 


( load the system pattern list ) 
sysPatterns := PatHandle(GetResource( 'РАТ“', 
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sysPatListID)); 


( go draw it and stuff ) 
MakePalette; 


( OverView normally creates & window that is a given 


fraction of the screen size. The number passed for 


the ratio is designed to create an exact sized 
rectangle the size of the palette. Ugly, but it 
works. } 

paletteFactor := CpopupViewRect bottom - 
popupViewRect.top) / (screenBits.bounds.bottom - 
screenB i ts .bounds . (ор-20); 

NewOverViewC myBitMap, patternPopUp, viewRect, 
paletteFactor, pleinDBox ); 


( Draw into the offscreen bitmap with DrawPoop ) 
UpdateOverView С DrawPoop, myBitMap ); 
end; ( InitPatternPalette } 


end. ( UNIT ) 


progrem PSample; 

(Compiler Switch Settings) 

( +) (renge checking on) 
($0V*) (overflow checking on) 


uses 
($U MemTypes.p ) MemTypes, 
($U QuickDrew.p) QuickDraw, 
($0 OsIntf.p — ) OsIntf, 
($U ToolIntf .p ) ToolIntf, 
($U UPalette.p ) UPalette; 


const 
AppleID = 1; ( Menu ID for Apple menu ) 
AboutItem = 1; ( About... commend ) 


FileID = 2; ( Menu ID for File menu ) 
NewWindowItem = 1; ( New window command ) 
QuitItem = 2; ( Quit command ) 


MenuBarHeight = 20; 


type 

PatRecord = record 
number : integer; 
thePattern : Pattern; 
end; 


PatRecPtr = ^PetRecord; 
PatRecHandle = “PatRecPtr ; 


ver 
AppleMenu : MenuHendle; 
FileMenu : MenuHandle; 


theWindow : windowPtr; ( the current front window ) 
oldPort : GrefPtr; ( temporary grefport info ) 
theEvent : EventRecord; ( for event loop ) 


systemPatterns : PatHendle; ( standard pattern list ) 


currentPattern : Pattern;( pattern for new windows ) 
currentPatNum : integer; ( id® for new windows ) 
programDone : Boolean; ( true if Quit is selected ) 
nextWindow : Point; ( governs window placement ) 


(------------------------- 


procedure SetUpMenus; 
ver 
( we need this cause the 'Apple' 
character isn't on the keyboard ) 
appleTitle: Stringi 1]; 
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begin 
( create Apple menu ) 
eppleTitle := ' '; 
eppleTitle[1] := chrC appleMerk ); 
AppleMenu := NewMenuC AppleID,eppleTitle 2; 
AppendMenu( AppleMenu, ‘Sorry, just for looks.;(-' ); 
InsertMenuC AppleMenu, 0 ); 


( create File menu ) 

FileMenu := NewMenu( FileID, ‘File’ ); 
AppendMenu(C FileMenu, ‘New Window’ ); 
AppendMenuC FileMenu, 'Quit' 2; 
InsertMenuC FileMenu, 0 ); 


( put it up on the screen ) 
DrawMenuBer ; 
end; ( SetUpMenus ) 


procedure MakeNewWindow; 

( Create & new window ) 

ver 
r : Rect; ( used for window size ) 
aWindow : WindowPtr; ( for NewWindow ) 


begin 
( use 1/4 screen space for rectengle ) 
with ScreenBits.bounds do 


begin 
r.top := top + MenuBarHeight;( ignore menu ber... 
r.left := left; 
r.bottom:= bottom div 2; 
r.right := right div 2; 


end; 
( offset placement of this window ) 


nextWindow.v := nextWindow.v + 20; 
nextWindow.h := nextWindow.h + 20; 


( too far down? ) 
if € nextWindow.v + 20 › ScreenBits.bounds .bottom) 
then nextWindow.v := 20; 


( too fer over? ) 
if С nextWindow.h + 20 > ScreenBits.bounds.right) 
then nextWindow.h := 20; 


( plece the rect ) 
OffSetRect( г, nextWindow.h , nextWindow.v ); 


( creete the window ) 
eWindow := NewWindowC nil, г, ‘Another Window', true, 


documentProc, pointer(-1), true, longint(0) ); 


SetPort( eWindow ); 


( force ап update event for this window ) 
InvalRect( thePort^.portRect 2; 


( create storage space for а pattern, end set it ) 

WindowPeek( aWindow 2^.refCon := 
longintC NewHandleC SizeOf(C PatRecord ) ) ); 

PatRecHandle(€ WindowPeek( aWindow 2^.refCon )** 
.thePattern := currentPattern; 

PatRecHendleC WindowPeekC aWindow )*.refCon 277 
“Number := currentPetNum; 

end; ( MakeNewWindow } 


procedure DestroyWindowC whichOne : WindowPtr 2; 

( We can't just do a DisposeWindow, because we ere 
maintaining an extra block on the heap that contains 
the current pattern for each window. We have to 
dispose of the block ourselves, because the WM 
doesn't know it's there.) 

begin 
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DisposHendleC handleC WindowPeekC whichOne )^ 
.refCon 2 ); 
DisposeWindowC whichOne 2; 
end; ( DestroyWindow ) 


procedure DoMenuC] ick; 
( Handle mouse-down event іп menu bar. ) 


ver 
menuChoice : longint; ( returned by MenuSelect ) 
theMenu : integer; ( ID of selected menu ) 
theItem : integer; ( number of selected item ) 
begin 


menuChoice := MenuSelect( theEvent.where ); 


( valid selection only if non-zero ) 
if menuChoice € @ then 


begin 
theMenu := HiWordC menuChoice 2); 
theItem := LoWordC menuChoice ); 


case theMenu of 
AppleID: ( don't really do anything ); 
( if they pick Quit, set global flag. 
if they pick New Window, go make one ) 
FileID: if theItem = QuitItem 
then programDone := true 
else if theItem = NewWindowItem 
then MakeNewW indow; 
end; ( cese theMenu.. ) 


( Unhighlight menu title ) 
HiliteMenuC 0 ); 


end; ( if menuChoice.. ) 
end; (DoMenuClick) 


procedure DoInContent; 
( handle mouseclicks in а window ) 
var 
tempPatNum : integer; ( temporary pattern number ) 
begin 
( this avoids inverting the "current selection" 
when popping-up the pattern ) 
tempPatNum: :PatRecHandleC WindowPeek( 
theWindow )*.refCon 2^^.number; 


( pop-up the pelette, and let them select a pattern ) 
PatternSelect( tempPatNum, theEvent.where ); 


{ a selection has been made only if 
tempPatNum has changed } 
if tempPatNum<>currentPatNum then 
begin 
( get the new pattern from the pattern list ) 
GetIndPattern( currentPattern, sysPatListID, 
tempPatNum); 
currentPatNum := tempPatNum; 


( force an update for this window ) 
InvalRect( thePort^.portRect ); 


end; ( if tempPatNum.. ) 


( set the pattern of the window ) 
PatRecHendleC WindowPeekC theWindow 2^.refCon 277 
.thePattern := currentPattern; 
PatRecHendleC WindowPeekC theWindow )*.refCon )** 
.humber :* currentPatNum; 
end; ( DoInContent ) 


procedure DoMouseDown; 
( Handle mouse-down events. ) 
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ver 


whichWindow : WindowPtr; ( window of mouse click ) 
thePart : integer; ( pert of screen of mouse click ) 
dragRect: Rect; ( а window-sized rect for DragWindow ) 
growVal: longint; ( window size after GrowWindow ) 
temp: Point; 


begin 


( where on the screen was mouse pressed? ) 
thePart := FindWindowC theEvent.where, whichWindow 2; 


сазе thePart of 

InDesk : (Do nothing); 
InMenuBar: ^ DoMenuClick; 
InSysWindow: ( Do nothing ); 


( if in top window then DoInContent, else make it the 
top window ) 
InContent: if whichWindow <> theWindow 
then SelectWindowC whichWindow ) 
else DoInContent; 


( if not in top window then make it the top window, 
then do dragging ) 

InDreg: begin 
if whichWindow «€? theWindow 
then SelectWindowC whichWindow 2; 
dragRect := screenBits.bounds; 
InsetRect( dragRect,4,4 ); 
DregWindowC whichWindow, 


theEvent .where, 


dragRect ); 
end; 


( if in grow box, resize window ) 
InGrow: begin 
SetRect( dragRect, 20, 20, 512, 342 ); 
growVal := GrowWindowC whichWindow, 
theEvent. where, dragRect ); 


( if non-zero, change the size of the 


window } 
if € growalog ) 
then begin 
SizeWindowC whichWindow, LoWord( 
growVal 2, HiWordC growVal 
), true ); 
InvalRect( thePort^.portRect ); 
( erase the port to prepare for 
updating ) 
FillRectC thePort^.portRect, white 
); 


end; ( if € growVal.. ) 
end; ( InGrow ) 


( if on go-away box, track till they let go ) 
InGoAway: begin 
if TrackGoAway( theWindow, 
theEvent.where ) 
then DestroyWindowC theWindow 


end; ( InGoAway ) 
end; ( case thePart of ) 


( таке theWindow the current front window ) 
theWindow := FrontWindow; 


( if there's а window up, do а SetPort ) 
if FrontWindow € NIL then SetPort( theWindow 2; 


end; (DoMouseDown) 


procedure DoUpdateEvent; 
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( handle update events ) 
ver 


whichWindow : WindowPtr; ( target of update event ) 
r : rect; ( temporary rect for clipping ) 


begin 
( get the window to be updated ) 
whichWindow := WindowPtrC theEvent.message ); 


( remember the current port before setting new port ) 
GetPortC oldPort ); 
SetPortC whichWindow ); 


( make a rect as big as the grow box ) 
r := thePort*.portRect; 
r.left := r.right - 15; 
r.top :» r.bottom - 15; 


( set the visRgn to & collection of the update regions ) 
BeginUpdateC whichWindow ); 


( set the clip to the whole window, 

and erase the grow box spot ) 
ClipRectC thePort^.portRect 2; 
FillRectC г, white) ; 


( drew the oval using the pattern pointed 

to by the window's refCon ) 

FillOvalC thePort^.portRect, PatRecHandleC 
WindowPeekC whichWindow )*.refCon 277. 
thePattern 2; 

Freme0valC thePort^.portRect 2; 


( drew the grow box, but only if this is the front window 


if FrontWindow = whichWindow then 
begin 
( clip to a rect barely as big as the grow box ) 
ClipRect( г ); 
DrawGrowIconCwhichWindow); 


( restore clip to be the whole window ) 
ClipRectC thePort*.portRect ); 
end; ( if FrontWindow = .. } 


( restore the visRgn of the window ) 
EndUpdate( whichWindow 2; 


( restore original port ) 
SetPortC oldPort ); 
end; ( DoUpdateEvt ) 


procedure DoActivateEvent; 
( handle activate and de-activate events ) 


ver 

targetWindow : WindowPtr; ( window being affected ) 

r : rect; ( temporary rect for clipping ) 
begin 


( get the window to be activated or de-activated ) 
tergetWindow := WindowPtr( theEvent.message ); 


{ remember the current port before setting new port } 
GetPortC oldPort ); 
SetPort( tergetWindow ); 


( make a rect just es big as the grow box ) 
г :* thePort^ .portRect ; 
r.left := r.right - 15; 
r.top := r.bottom - 15; 


if OddC theEvent modifiers ) 
then begin ( it's an activation ) 
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( make it the top window ) 
SelectWindowC tergetWindow 2; 


( clip and draw the grow box ) 
ClipRect( г 2; 
DrewGrowlcon( tergetWindow ); 


( restore the clip to the whole window ) 
ClipRectC thePort^.portRect 2; 

end 

else begin ( it's a de-activation ) 


( Force ап update of this window. Only the area 
occupied by the grow box will be updated ) 
InvalRect( r 2; 


( restore the port ) 
SetPortC oldPort ) ; 
end; ( if OddC. ) 


end; ( DoActivateEvent ) 


begin ( main ) 


InitGrafC @ThePort 2; { obligatory material goes here ) 
InitFonts; 

Ini tWindows; 

Ini tMenus; ( <-- boring initialization code ) 
TEInit; 

InitDialogsC NIL ); 

InitCursor; 


( kick stert the pop-up palette ) 
InitPatternPalette; 


( go put up some menus ) 
SetUpMenus; 


( load the system pattern list ) 
systemPatterns := PetHendleC GetResource( 'РАТ#', 
sysPetListID ) ); 


currentPatNum := 1; 
( start currentPattern at black (pattern #1) ) 
GetIndPattern( currentPattern, sysPetListID, 1); 


( start window placement et 20,20 ) 
SetPtC nextWindow, 20, 20 ); 


( put up the first window, end meke it 'theWindow' ) 
MakeNewWindow; 
theWindow := FrontWindow; 


( this gets set to true when Quit command is selected ) 
progremDone := false; 


( here's the main event loop ) 
repeat 
if GetNextEventC everyEvent, theEvent ) then 
cese theEvent.what of 
MouseDown: DoMouseDown; 
UpdateEvt: DoUpdateEvent; 
ActivateEvt: DoActivateEvent; 


( if you're not handling an event, 
let the system have some time ) 
otherwise SystemTesk; 
end; (cese) 
until progremDone; 


( now let's dispose of eny windows still up ) 
while FrontWindow € NIL do 
DestroyWindowC FrontWindow 2; 
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Pop-Up Pallettes in Overview 
David Wilkins 
Eugene, OR 
(From Letters Column Vol. 3 No. 11) 

There is a bug in Greg's new Overview unit (in the July 1987 
Mactutor). He changed procedure NewOverView to include a 
windowkind parameter, noting that the change was "purely 
cosmetic, but that's what Mac programming is all about". 

The change is much more than cosmetic, as I discovered when 
I tried a windowKind other than plainDBox. DocumentProc 
leaves behind on the screen a ghostly image of the window's 
frame. The problem is the window manager draws the window 
frame outside of the window's bounds rectangle. OverView 
incorrectly assumes that restoring the window's bounds rec- 
tangle would restore all bits under tha window. Not so with the 
fancier window types. 

There are at least three fixes: 

1) Easiest, least elegant: remove the WhatKind parameter. 

2) Also fairly easy: save and restore the entire screen image, 

rather than just the area under the window's contents. 

3) Enlarge the area saved and restored by 20 or 30 pixels to 


allow for various window frame styles. 

While investigating the peculiarities of window behaviors, I 
managed to achieve a number of truly spectacular screen 
wipeouts. Appearently I wiped out bits above the screen bit 
image. The fix is pretty simple— set some strict limits on the 
rectangle to be saved and restored, to limt it to be well within the 
confines of the ScreenBits.bounds, and at least 20 pixels below 
the top of the bounds to prevent damage to the menu bar. 

I would like to hear Apple's comments on the avisability of 
directly messing with windows— the Mac II is clearly showing 
that it pays to think ahead about compatibility issues. // can tell 
you their comment: Don't! Multi-Finder now owns the windows. 
-Ed] 

By the way, I successfully implemented OverView with 
Lightspeed Pascal. I had to include a couple of extraneous 
assignment statements to allow access to a few of the window 
fields; LSP just does not like to type cast on the left-hand side of 
an assignment statement. Other than that, it works fine. 


Ом! 


ғғ 
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Pascal Procedures 
Animated BitMaps 


Offscreen BitMagic 


Remember the first time you picked up an object in Déja Vá 
or Uninvited? Absolutely dazzling! The object lifted off the 
page. You dragged IT around, not some gray outline. Ever 
wondered how animation like that is done? Obviously some of 
you have, because we've seen similar behavior in other pro- 
grams. Just about all of the paint programs have it. Maybe you 
can think of others that do it, too. 

Alan Kay loves to point out that, about ten years ago, Alto 
computers at XEROX Palo Alto Research Center (PARC) per- 
formed at about the same level as today's Macintosh Plus. We 
now have the power to pay attention to feel and effect. Alan Kay 
showed a film of a current XEROX PARC project called the 
Alternate Reality Kit. It served as my inspiration for the effect 
that serves as the focus of this article. I realized that the Mac is 
plenty powerful to drag whole objects, and it might even be 
powerful enough to add shadows. The sample programs below 
show that my hunch was right. Try them out and see if you don't 
feel a sense of excitement as the pictures leap off the screen and 
move around. 

In addition to the samples, this article discusses some of the 
how-to's of offscreen bitmap magic. It also provides you with 
code that you can plug directly into your programs. Now that we 
havea machine that can handle it, let's push it. Let's see what this 
can do for our interfaces. Figure О shows our example program, 
which allows us to drag various bitmaps without flicker. 


Where do we start? 


Try to imagine how you might solve the problem of dragging 
apicture around the screen if you could do it any way you wanted. 
I envision a graphics system where I could define arbitrarily— 
large sprites on many different planes. I could then place an 
object anywhere simply by specifying the x,y coordinates for the 
upper-left-hand corner of the sprite. OK, so we don't have that 
(yet...). Frame buffers, yeah, thatcould doit. No? Hmm... How 
about a hardware blitter that would also make it very fast to draw 
directly on the screen? We don't have that either? All right, all 
right, I'll push back my expectations a bit, and I won't even think 
of mentioning the alternate screen... 

Suppose we do all of our drawing on the screen. No problem, 
right? No problem, except that it produces a very annoying side 
effect — flicker. Blech! Why does flicker happen? It’s all rather 
simple. Basically, when you want to animate an object, you draw 
it somewhere, erase it, then draw it somewhere else, over and 
over. Now when you erase it, you have to put back whatever was 
underneath the object. If the user gets to watch these steps, flicker 
results. If you can draw everything very rapidly, then you might 
not even see all the drawing happen, especially if you make sure 
that your drawing happens during the period of time when the 
raster beam is travelling from the bottom to the top of the screen 
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Scott Boyd 
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EI Bryan, Texas 
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Fig. 0 A Moving large bitmaps flicker free... 


Fig. 0 B Dragging Smalli bitmaps with shadow... 


(the vertical blanking period). And, hey, you've got loads of 
time: 1.26 milliseconds. Of course, you get to splitthat time with 
all the VBL tasks. That's still plenty of time to animate an icon 
if you use assembly language to draw directly into screen 
memory without QuickDraw calls. Unfortunately, that's not 
nearly enough time for much else. 

At this point, you might be tempted to go find a machine with 
the hardware support listed above. I don't blame you, but fear 
not. We already know the Mac can do it, the question is, “If not 
the above methods, how, then?" The solution which follows 
seems a bit strange, but it works nicely. I think you'll find it 
simple to use the code presented here in your own programs. 


Living Flicker-Free: Offscreen Bitmaps 
The magic ingredient that lets us avoid flicker is something 


called an offscreen bitmap. What you see on your Mac screen 
belongs to a bitmap called ScreenBits. It's an onscreen bitmap. 
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Offscreen means that you can't see it. Fortunately, QuickDraw 
can. Youcan use as many offscreen bitmaps as you have memory 
toallocate. By drawing into them, youcan prepare a scene before 
bringing it onto the screen with the surprisingly fast CopyBits 
routine. The user won't see the drawing taking place. It leaves 
the user with the impression that the program is faster. For some 
reason, most users associate flicker with poor performance. 

If youaren'tquite up to a bunch of technical details about why 
this works, go ahead and skip to the next section to see how you 
can use it. 

Whatis a bitmap? Inside Mac defines itas a record with three 
fields. The first is rowBytes, which tells how many bytes of 
storage are needed for each row. RowBytes must be an even 
number because QuickDraw uses rowBytes to calculate ad- 
dresses, and addresses must always be even on a 68000 (anda lot 
of other machines). The second is bounds, a Rect which defines 
the height and width and coordinate system. Third is baseAddr, 
a pointer to the chunk of memory rowBytes*(the height) bytes 
big. You get a bitmap to play with by declaring a bitmap variable 
and filling in all three fields. To fill in baseAddr, you must 
allocate the memory. See the code (function NewBitMap) for 
my favorite way to set up a new bitmap. 

Now that you have a bitmap, how do you getto use it? Perhaps 
youare familiar with that field of the grafPort called portBits. By 
default, a grafPort has screenBits in the portBits field. You can 
substitute your own by using SetPortBits. Any subsequent 
drawing will take place in your bitmap. The primary difference 
is that you won't be able to watch the drawing unless you copy 
that work onto the screen. 

So how are we going to drag objects around? Simple. We'll 
use a whole bunch of offscreen bitmaps to prepare each frame of 
our interactive animation. One approach requires two bitmaps 
the size of the screen plus one the size of the picture to drag. 
Before dragging begins, a copy of the screen is made into both of 
the screen-size bitmaps and the picture is drawn into the picture 
bitmap. 

The following steps form the animation cycle. To repair the 
area where the picture was last time, copy from the virgin bitmap 
into the working bitmap enough area to cover over the picture. At 
this point, the working bitmap is identical to the virgin bitmap. 
Now copy the picture onto the working bitmap in the new 
location. The frame iscomplete, socopy itto the screen. The user 
sees, in one shot, a complete new image. The amount copied to 
the screen must include the area under the picture where it is now 
and where it was last time. If the picture is allowed to move 
anywhere on the screen in one step, the amount copied to the 
screen might need to be as large as the whole screen. If you limit 
movement so it can only move a limited distance each step, you 
can find ways to use less memory. 

This approach works well for a large number of cases. This 
method is very quick, but usually a memory hog. Since my 
interest was in dragging objects anywhere on the screen, I felt that 
the cost of keeping an entire extra screen-size bitmap might prove 
prohibitive. The second method (presented below) saves a little 
space at the expense of some additional copying. A third method 
capitalizes on the first method, but requires that you limit the 
movement of the object to a specified area, say a window or 
control’s rectangle. Then, rather than screen-sized bitmaps, you 
can use bitmaps the size of your limiting area. As with most 
programs on the Macintosh, you always have a number of ways 
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to achieve the same result. Darin Adler of ICOM says a real Mac 
programmer should be able to think of at least three ways to solve 
a Mac problem. Maybe you can think of other approaches. 

This method requires more bitmaps than the previous one, but 
only one screen-size bitmap to hold the copy of the screen. 
Another bitmap holds a picture of the object. Yet another has 
something new — a shadow which can be positioned independ- 
ently. Two more bitmaps round out the collection, and they act 
as temporary storage for what’s under the picture and the shadow. 

Here’s what happens. First, we save a copy of the bits we’re 
about to blast with our drawing (Figure 1). Figure 2 shows an 
example of putting an object and its shadow on the screen. Once 
we're into the animating loop, we do the following things. The 
bits underneath the place where the picture and the shadow need 
to be saved, as shown in Figure 3. We then draw the shadow on 
thecopy of the screen. Then we draw the picture (Figure 4). Then 
we show our offscreen work on the screen, as in Figure 5. Lastly, 
while the user isn't looking (either because he's too busy being 
amazed or maybe just because he can't see it), we fix up the copy 
to look like it did before we drew on it (Figure б). Just do this over 
and over, and, voíla, you're an animation magician! 

Andnow the technical description. This technique uses three 
phases: preparation, dragging, and cleanup. 


Preparation 
PO Allocate bitmaps 
P1 Erase pictureBits & shadowBits 


P2 Create the region from the picture 
P3 Draw the shadow into shadowBits 
P3 Draw the picture into pictureBits 
P4 Copy the screen into offScreenBits 
Dragging 


DragRect is a rectangle the size of the picture's 
picFrame. It is positioned on offScreenBits 
where the picture is to be drawn. 


DO Save the bits underneath dragRect from 
offScreenBits into underBits 

D1 Save the bits underneath dragRect (offset to the 
shadow position) into underShadowBits 


D2 Draw the shadow from shadowBits into 
offScreenBits 

D3 Draw the picture from picturebits into offScreen- 
Bits 

D4 Copy portions of offScreenBits onto screenBits 

D5 Replace bits underneath from underBits to 
offScreenBits 

D6 Replace bits underneath from undershadowBits 
to offScreenBits 

Cleanup 

CO Restore screenBits with offScreenBits 


C1 Get rid of the bitmaps, regions, and grafPort 

After step D6, offScreenBits is identical to screenBits before 
all the animation started. ScreenBits, on the other hand, is 
showing the picture drawn in D2-D3. Notice that the only time 
any drawing is done on the screen is in step D4. Change where 
it says "portions" to read “Ше intersection of the two rectangles 
from the current frame and the previous frame" and you can see 
that this is the magic step. 

Here's why: ScreenBits is showing the latest frame. We 
don't want the user to see the individual drawing steps. So, two 
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Fig. 3 Save the bits underneath 
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Fig. 2 Multiple bitmaps for moving trash can 
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ShadowBits underPictureBits underShadowBits 


Fig. 4 Next, draw shadow and bitmap 


things must happen to the screen each frame. The stuff under the 
last position of the object must reappear and the object must 
appear in its new position. 

The approach I chose takes the union of the two rectangles 
enclosing the old and new positions. That new (larger) rectangle 
encompasses all of the area that must change in the new frame. 
If the contents of the offscreen bitmap have been prepared 
correctly, CopyBits can copy the whole big rectangle in one call. 
CopyBits handles arbitrary regions well enough, but it is opti- 
mized for rectangular regions, so I chose to use UnionRect rather 
than UnionRgn. Since object dragging should be as realistic 
(speedy) as possible, every little optimization helps. By copying 
the minimal bounding box of the two rectangles from offScreen- 
Bits to screenBits, the old one vanishes and the new one appears 
all at once with a one-step update. 
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The Code 

The code presented here includes a separate compilation unit 
and three sample programs, all written using MPW Pascal. The 
first sample program loads a picture from the resource fork, waits 
for a mouse Click, draws the picture, then lets you drag it around 
until you release the button. The second sample waits for a 
mouseDown and then animates every picture in all open resource 
forks (one at a time), bouncing them around the screen. The 
Cursor position is used to set its velocity. The third sample was 
written by Greg Marriott. It demonstrates how to use your own 
bitmaps rather than having them allocated by my code. 

By plugging in your own pictures, the sample programs 
should give you a good idea of the responsiveness and feel you 
can have when you use this code in your own programs. 
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Fig. 5 Offscreen bitmap copied to screen 


The unit DragManager has the following calls: 


function InitDrag С userOffscreenBits : bitMapPtr ) : 
boolean; 

function NewDraggable С thePicture : PicHendle; 
userPicBits, userShadowBits : bitMapPtr; 
ver dragStuff : DragHandle ) : boolean; 

procedure DragItTo С dragStuff: DregHendle; 
mousePt: point; 
centered: boolean); 

procedure DisposeDraggable С dragStuff : DragHandle ); 

procedure UpdateOf fScreen ( dragStuff : DragHandle; 
Procedure drawProc 2; 

procedure CloseDrag С disposeBitMap : boolean 2); 


InitDrag is called once before you want to drag things 
around. If you pass it a bitmap, it will use that instead of 
allocating its own to hold the copy of the screen. InitDrag will 
draw on it, but you can do your own drawing on it afterwards. 
InitDrag returns false if it fails in any of its allocation. Call 
NewDraggable with the picture you want to drag around. The 
picture's picFrame is used for the size of the bitmaps it will use. 
If your picture extends outside of its picFrame, those portions 
will be missing. If you pass in bitmaps, they will be drawn on, 
but you can change them after the call. NewDraggable returns 
false if it fails in any of its allocation. DragItTo positions the 
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Fig. 6 On-screen fix-up of underneath bits 


picture centered over a point on the screen. If you'd rather have 
the picture drawn below and to the right of the point, pass false 
for centered. 

Call DisposeDraggable when you are through with the 
picture. It deallocates everything and removes the last picture 
from the screen. If you wish to leave the picture's stuff allocated 
but want to remove the picture from the screen, do a DragItTo 
with a position way off the screen. UpdateOffScreen lets you 
draw on the copy of the screen. Pass it the name of a procedure 
you want it to call which will do your drawing. This could be 
useful for a variety of effects. CloseDrag disposes of the stuff 
InitDrag allocated. 

InitDrag and NewDraggable are set up to allow you to pass in 
your own bitmaps rather than having them allocated automati- 
cally. If you do pass them in, be forewarned that DisposeDrag- 
gable and CloseDrag dispose of those bitmaps. You can still get 
rid of everything else without deleting your bitmaps if you set the 
appropriate bitmap baseAddr fields in your dragStuff record to 
nil before calling DisposeDraggable. If you want CloseDrag to 
getrid of the screen-size bitmap, pass in true for disposeBitMap. 

I'm still looking for a chance to try using this code in other 
programs to replace my calls to DragGrayRgn, so bear with me 
if you have problems (and please let me know). For an interesting 
experiment, you might try using this or similar code to replace the 
DragGrayRgn trap. 

Using Offscreen Bitmaps 

This code is set up to teach you some of the tricks of non- 
flickering animation on the Mac. You can (and should) modify 
my approach to take advantage of your own data structures. For 
example, we here at the MacHax™ Group wrote a drawing 
program called Whatever... (the name was unwittingly sug- 
gested by Gustavo Fernandez and Darin Adler — hi guys!). All 
of our drawing happens offscreen. If we chose toreplace our calls 
to DragGrayRgn with this dragging code, we’d be crazy to go 
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allocating more bitmaps. We keep a lot of bitmaps, pictures, and 
regions handy for just such an occasion. 

The technique presented here requires an entire offscreen 
bitmap. Consider that а large screen using one bit per pixel could 
easily chew up over 130K. Now consider the implications of 
color (2, 4, and 8-bit). Clearly, a better technique is called for. 
I've found a way to use less memory, but, as in most good 
computer solutions, it involves the space-time tradeoff, costing 
almost twice as much in processor time. If you thought the above 
method was convoluted, you'll be glad I didn't write up the new 
method. 

Related MacHax MacTips 

Now here are some of the lessons learned recently here at the 
MacHax Group. 

• Don’t use PatOr when you mean SrcOr. The effects when 
using CopyBits are spectacularly wrong. Since both types are 
really the same TYPE, the compiler let it through. Just glancing 
at it, it looked right. However, watching the results, it quite 
clearly was incorrect. Rather than OR'ing in the bitmap, it filled 
in some (apparently) arbitrary pattern which would change 
randomly every now and then. Hmm... still can't explain it, but 
Ican tell you to avoid it unless you like bizarre behavior. 

* CopyBitsrespects the clipRgn and visRgn if the destination 
bitmap belongs to the current port. This can bite if, for example, 
you are using the window manager port and your bitmap crosses 
screenBits.bounds. You can detect such a problem when you 
notice that a portion of your bitmap whose boundsRect isn't 
entirely within screenBits.bounds seems to be filled with garbage 
even after you erased the whole bitmap. You can avoid this 
problem by setting both the clipRgn and visRgn to the size of your 
offscreen bitmap long enough to do your drawing. 

* DrawPicture also cares about the clipRgn and visRgn. It 
seems obvious, but even obvious things can slip by. Is it just me, 
or do other people wish the QuickDraw chapter had more in it? 

* NewDraggable uses DrawPicture inside OpenRgn / Clos- 
eRgn to build a region. It is quite possible to run out of memory 
as theregion is built. I have found pictures that will send my Mac 
into the weeds. Those pictures are so incredibly complex that it 
doesn't surprise me at all, nor would I really want to drag them 
around. Justuse somecommon sense about the pictures you want 
to drag around. Bitmaps are very simple, and the Drag Manager 
is quite capable of dragging around a full-screen bitmap. 

• Don't InvalRect or InvalRgn when your current port is а 
grafPort without a window. The update region is maintained as 
a part of the window, not the grafPort. Trying to change the 
updateRgn of a port without a window will mess with things on 
past the grafPort, resulting in unpredictable behavior. This is 
reason #395 in the book Why Macintosh Runs Into Trees. 

е Reason #396 has to do with bitmap bounds. If they are too 
big, i.e. not enough memory was allocated, filling the bitmap will 
trash other variables that just happen to have made the mistake of 
moving next door. In the particular instance which taught us this 
lesson, three bitmaps were declared all in a row. The first one's 
baseAddr size was too small when calculated, so the bitmap 
wasn't allocated big enough. When we filled it with white, the 
next bitmap was deallocated, the heap was corrupted, and the 
stage was set for disaster. The next time memory was requested, 
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the memory manager went looking for free blocks. When it hit 
that one, the wheels locked, the Mac went out of control, and we 
were unwrapping it from around a large oak. 


* BUG REPORT! (subtle, huh?) As hard as we try, bugs 
just seem to slip through. Although no bugs in OverView (Sept. 
86) were ever reported, the above investigative debugging re- 
veals that the code used to allocate bitmaps has a problem. If 
(width div 16) « 8 then rowBytes is calculated two bytes too 
small, resulting in a bitmap allocated 2*(bottom-top) bytes too 
small. Somehow we've managed to avoid the problem, although 
it might explain the difficulty reported with using a certain value 
on a Lisa (tried once and forgotten). NewBitMap corrects this 
problem. 

Programming grains of sand' 
(* pearls in the rough?) 
Offscreen Bitmaps 

Whenever your work involves drawing, especially any kind 
of interactive drawing or animation, offscreen bitmaps provide a 
mechanism for smooth, flicker-free drawing. While CopyBits 
penalizes you (albeit very slightly) by chewing up some time to 
get the changed material from the offscreen bitmap into screen- 
Bits, users generally perceive a performance enhancement. In 
addition, responding to update events requires no more than a 
single CopyBits if you have the full screen or window offscreen. 
As with most computer science problems, this trades off a little 
time and space for very fast response times. If you have the 
memory to spare, this beats watching something like PageMaker 
or MacDraw redraw all five grillion little objects while you sit 
and wait to get back to work. When it comes to watching those 
tedious updates, any program that doesn't use offscreen bitmaps 
is wasting its time. No, strike that, wasting our time. As you will 
see in the next paragraph, italso gives you a ‘free’ screen to draw 
on. Fast updates aren't the only benefit, you can also let your 
window contents keep up while scrolling. 


Take a look at your data 


View your data structures when you have questions about 
their behavior. This especially holds true if you are working with 
structures that have a useful visual interpretation. To make sure 
that my offscreen bitmaps were behaving themselves, I copied 
them onto the screen after drawing into them. This technique 
helped me track down the two biggest problems I had with 
developing this code. The last bad problem was that I was 
copying from shadowBits to the offscreen bitmap. I had gener- 
alized some of my code and things stopped working (see below). 
By copying shadowBits to screenBits directly, I discovered that 
shadowBits held the correct stuff, so the problem was narrowed 
down to the CopyBits call where I discovered the patOr/srcOr 
problem above. 

Now where does that free screen come from? Since I put 
shadowBits directly on the screen, I want to be sure that the 
screen won't be destroyed. That's easy. Remember that I have 
acopy of the screen in offScreenBits. All my drawing takes place 
offscreen, so screenBits is a good place to do debug-drawing. 
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Generalize your code 

This is the hard part. I had essentially what you see here 
running in one evening. Most good ideas happen that way. 
However, to present it to you in a clear fashion required much 
more work. I’m going to try to convince you that polishing the 
code is worth the effort. 

For one thing, if you polish it, use it in a program, and write 
up an article, you can publish it, and that benefits your readers. 
For another, you'll find that you need to reuse portions of it for 
some other project on down the road. If it’s a good idea, it’s worth 
doing right. You never know how many places you can plug in 
your code if it’s been generalized and documented. 

If you put the effort into presenting it to others, you will find 
that you can still read your work a year from now. It’s the 
strangest feeling to wonder how to do something with pop-up 
windows, then to go pull out the article I wrote to see how to do 
it. Call it bizarre, but I’ve done that at least five times since last 
year. On top of that, nothing teaches as well as a good example. 
Thanks to Darin Adler and the many MacTutor authors who have 
provided our community of Mac programmers with good ex- 
amples. Not that Darin documents the examples he’s given me, 
but working code often speaks for itself. It was his idea to write 
and collect solutions that can be used to extend the toolbox. It’s 
in that spirit that this work is offered to you. 


Robusticize your code 


A necessary part of generalizing your code is making it as 
bomb-proof as possible. You might notice that I check just about 
every time a memory-allocating operation is done. I don’t like 
having to do that. I’ve always expected an operating system to 
take care of failed memory allocations with an exception-han- 
dling mechanism, but the Mac (and/or Pascal’s runtime system) 
won't do that for us yet. It makes the code longer and a little 
harder to read, but I guarantee the programs are a little harder to 
crash than when I first wrote them thinking, *Well, I'll just never 
try passing in too big a picture." Right. The first time I ran it in 
the MPW Shell with the Scrapbook DA open, the Mac found the 
nearest tree to smash into. 

I've enjoyed working on this, and have a number of plans for 
improving it even further. If you have questions or suggestions, 
drop mea note at boyd(2 tamlsr on bitnet, S.T. BOYD on GENIE, 
or 3420D Sandra, Bryan TX 77801 on USnailNet. I would also 
be very interested to see your solutions and how you use them. 
And, naturally, I couldn't end this without thanking TECHNOS- 
TUD himself (aka Steve Knouse of Apple Computer) for his 
relentless browbeating and support. 

UNIT DragManager ; 

(Version 1.0 Saturday, April 18, 1987 by Scott T. Boyd of 
the MacHax™ Group. Many thanks to Greg Marriott, also a 
member of the MacHax Group. 9 1987 by The MacHax Group, 
Bryen, TX.) 

($0*) (put in debug names} 

($R+} {range checking on) 


($0V*) (overflow checking on) 
($N*) {pass routine names to linker) 
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INTERFACE 
USES ($LOAD pinterfaces.dump) 


MemTypes, QuickDrew,OsIntf , PasL ibIntf , ToolIntf , 
PackIntf , IntEnv, CursorCt!; 


pe 
shadowRecord = record 


var 


visible : boolean; 
dx, dy : integer; 
thePattern : Pattern; 
copyMode : integer; 


end; 

dragHandle = “dragPtr; 
dragPtr = “dragRecord; 
dragRecord = record 


shadowBi ts, (the shadow) 
underShadowBits, ^ (what's under the shadow) 
underBits, (bits obscured by picture) 


pictureBits : BitMap; (the picture) 
shadowReg ion, 
thePictureRgn : RgnHandle; (use this for masking) 


end; 
bitMapPtr = ^BitMap; 


shadowStuff : shadowRecord; 


function InitDrag ( 


userüffscreenBits : bitMapPtr ) : boolean; 


function NewDraggable С thePicture : PicHandle; 


userPicBits, userShadowBits : bitMapPtr; 
var dragStuff : DragHandle ) : boolean; 


procedure DragItTo ( 


dragStuff: DragHandle; mousePt: point; 
centered : boolean ); 


procedure DisposeDraggable ( dragStuff : DragHandle ); 


procedure UpdeteOffScreen ( 


dragStuff : DregHendle; 
Procedure drawProc ); 


procedure CloseDrag ( disposeBitMap : boolean ); 


IMPLEMENTATION 
const 
shadow_x = 4; 
shadow_y = 6; 
ver 
offScreenBits : BitMap; (the picture) 
wMgrPort, 
oldPort, 
offPort : GrefPtr; 
updateRegion : RgnHendle; 
lestRect, (this + dregRect =› updateRegion) 
otherUpdateRect,  (updateRect clipped to include only 
bits onscreen) 
updateRect, (union of dragRect and lestRect) 
dregRect, (size of the picture & centered 


over cursor) 
tempBounds : Rect; (used in creating bitmaps) 


mousePt, 
otherMousePt, 
testPt : Point; 


(used to position dragRect} 
(used to see if cursor has moved) 
(used to see if cursor has moved) 


synchCount : longint; (wait for TickCount to change 
before drawing) 


procedure Debugger; INLINE $A9FF; 


function NewBitMepC var theBitMap : BitMap; 


beg! 


theRect : Rect ): ptr; 
n 
with theBitMap, theRect do 
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begin 
rowBytes := ((right-left*15) DIV 16) * 2; 
baseAddr := NewPtr(rowBytes * longint(right - left)); 
bounds := theRect; 
if MemError © noErr then NewBitMap := nil 
else NewBitMap := baseAddr; 


end; 
end; (NewBitMap) 


function InitDrag C userOffscreenBits : bitMapPtr ) : 


boolean; 
begin 
InitDrag := false; 


(do al] the work in the wMgrPort) 
GetPort( oldPort ); 
GetWMgrPort( wMgrPort ); 
(now make an offscreen bitmap to hold the whole screen) 
(if one already exists, ignore what they pass in} 
1f user0ffScreenBits € nil 
then offScreenBits := BitMapCuser0f fScreenBits^) 


13е 
1f NewBitMapCof f ScreenBits,screenBits.bounds) = nil 
then exitC InitDrag 2; 


(meke the grafport to play with. this wey I can really 
trash up the grafport and not worry about saving and 
restoring the old one 
offPort := GrefPtrC NewPtrC sizeofC GrafPort ) ) ); 
1f offPort = nil then 
begin 
DisposPtr( offScreenBits.baseAddr ); 
exitC InitOrag 2; 


end; 
(set up off screen port so we can drew in it) 
OpenPort( offPort ); 
RectRgn( thePort^.visRgn, thePort^.clipRgn^^.rgnBBox ); 


(create the region to update with) 

updateRegion := NewRgn; 

1f updateRegion = nil then 

begin 
DisposPtr( offScreenBits.baseAddr ); 
ClosePort( offPort ); 
DisposPtr( Pointer offPort 2); 
SetPort( oldPort ); 
exitC InitDrag ); 

end; 


(set up the default shadow stuff) 
with shadowStuff do 
begin 
visible := true; 
dx := shadow_x; 
dy := shadow_y; 
thePattern := black; 
copyMode := SrcXor; 
end; 
(copy the screen} 
CopyBite( screenBits, of fScreenBits, screenBits.bounds, 
offScreenBits.bounds, srcCopy, nil ); 
InitDrag := true; 


SetPoert( oldPort ); 
end; (InitDreg) 


function NewDraggable C thePicture : PicHandle; user- 
PicBits, userShadowBits: bitMapPtr; 
var dragStuff: DregHendle ) : boolean; 
procedure TestNil C theThing : ptr ); 
begin 
if theThing = nil then 
begin 
DisposeDraggable С dragStuff ); 
NewDraggable := false; 
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SetPort( oldPort ); 
exit С NewDraggable ); 


end; 
end; (TestNi1) 
begin 

GetPortC oldPort ); 
SetPort( offPort ); 
dragStuff := DregHendleCNewHendle(sizeOf CdregRecord22); 
1f dregStuff = nil then 
begin 

NewDraggable := false; 

SetPort( oldPort ); 

exitC NewDraggable ); 
end; 


MoveHH1C Handle( dragStuff 2); 
HLock( HendleC dragStuff ) ); 
with dragStuff^* do begin 
(try to allocate and erase the following bitmaps 
- pictureBits holds the bitmap to display 
- shadowBits holds the shadow 
underBits holds the bits obscured by the picture 
underShadowBits holds the bits obscured by the shadow 
offScreenBits holds the entire screen’s image 


{create a bitmap for the picture the size of the picframe) 

tempBounds := thePicture^^.picFrame; 

1f userPicBits © nil 

then pictureBits := BitMapCuserPicBits^) 

else TestNil С NewBitMapC pictureBits, tempBounds ) 2; 
(now create the drop shadow bitmep) 

1f userShadowBits © nil 

then shedowBits := BitMapCuserShadowBits^) 

else TestNil С NewBitMap( shadowBits, tempBounds ) ); 
(home tempBounds before setting up underBits) 

with tempBounds 

do OffSetRect( tempBounds, -left, -top ); 

TestNil С NewBitMepC underBits, tempBounds ) 2; 
(neke the under-the-shadow bitmap the seme size as the other 
underBi ts) 

TestNil С NewBitMap( underShadowBits, tempBounds ) ); 
(clear out the bitmap for the picture) 

SetPortBitsC pictureBits ); 

EreseRect( pictureBits.bounds ); 


(neke & region for the drop-shadow) 
shadowRegion := NewRgn; 
TestNil С pointerC shadowRegion 2); 
(drew the picture into pictureBits & create thePictureRgn) 
thePictureRgn := NewRgn; 
TestNil € pointerC thePictureRgn 22; 
OpenRgn; 
HLockC HaendleC thePicture 22; 
DrawPicture( thePicture, thePicture^^.picFreme ); 
HUnlock( HaendleC thePicture 2); 
CloseRgn( thePictureRgn ); 
if EmptyRgn( thePictureRgn ) 
then RectRgnC thePictureRgn, thePicture^^.picFreme ); 
(put the picture in pictureBits 
SetPortBits( pictureBits ); 
HLockC Handle€ thePicture 2); 
DrewPictureC thePicture, thePicture^^.picFreme ); 
HUnlock( HendleC thePicture 22; 


(clear out shadowBi ts) 
SetPortBits( shadowBits ); 
EraseRect( shadowBits.bounds ); 
(fill in the shadow) 
CopyRgn( thePictureRgn, shadowRegion ); 
PenMode( PatCopy ); 
PenPat( shadowStuff.thePattern 2; 
PaintRgn( shadowRegion 2; 
Of fSetRgn(shadowRegion, shadowStuff .dx, shadowStuff .dy); 
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(the bounding rect surrounding the picture in position) 
dragRect := pictureBits.bounds; 


SetRect( lestRect, 0,0,0,0 ); 
end; (with dragStuf f^^] 
HUnlock( HandleC dragStuff ) 5; 
NewDraggable := true; 
SetPort( oldPort ); 
end; (InitOrag) 


procedure DragItTo ( dragStuff: DragHandle; mousePt: point; 
centered : boolean 2; 


begin 

(we’11 do all our work in the window manager port) 
GetPort( oldPort ); 
SetPort( offPort ); 


MoveHHiC HandleC dragStuff ) ); 
HLock( HandleC dragStuff ) ); 
with dragStuff** do 
begin 
otherMousePt := mousePt; 
(home the region, the rect and the shadow region) 
Of fSetRgnCthePictureRgn, -dragRect . lef t, -dragRect . top); 
Of FSetRgn(shadowRegion,-dragRect. lef t, -dragRect . top); 
Of fSetRect(dragRect , -dregRect . left, -dregRect top); 
(center the object over the cursor) 
(calculate mousePt here because we know the rect is home'd) 
1f centered then 
begin 
mousePt.h := mousePt.h - dragRect.right div 2; 
mousePt.v := mousePt.v - dragRect.bottom div 2; 


end, 
OffSetRect( dragRect, mousePt.h, mousePt.v 2; 
OffSetRgn( thePictureRgn, mousePt.h, mousePt.v ); 
OffSetRgn( shadowRegion, mousePt.h, mousePt.v ); 


(save bits underneath the shadow and ) 
(then the bits under the picture} 
if shadowStuff . visible 
then begin 
(work with the rectangle around the shadow) 
with shadowStuff do OffsetRect( dragRect, dx, dy ); 
(remove апу pert of dregRect which is off the screen) 
if SectRect( screenBits.bounds, dregRect, updateRect ) 
then 0; 
(the destination rectangle will be home'd) 
otherUpdateRect := updateRect; 
with otherUpdeteRect do 
OffSetRectC otherUpdateRect, -left, -top 2; 
(teke the snepshot) 
CopyBits( offScreenBits, underShadowBits, 
updeteRect, otherUpdeteRect, srcCopy,nil 2; 
{move dragRect back over the picture area) 
with shadowStuff 
do OffsetRect( dragRect, -dx, -dy ); 
end; (only if visible) 


(clip dragRect to inside the screen} 
1f SectRect( screenBits.bounds, dragRect,updateRect ) 
then (; 
(home the destination rect) 
otherUpdateRect := updateRect; 
with otherUpdateRect do 
OffSetRect( otherUpdateRect, -left, -top 2; 
{зау "cheese"^) 
CopyBitaC offScreenBits, underBits, 
updateRect, otherUpdateRect, srcCopy,nil ); 


(draw my object’s shadow. 
=) modification point <= if the copyMode is srcCopy 
you should use shedowRegion to mask instead of nil.) 


1f shadowStuff .visible 
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then begin 
with shadowStuff do OffsetRect( dragRect, dx, dy 2; 
CopyBitsC shadowBits, offScreenBits, 
shadowBits.bounds, dragRect, 
shadowStuf f .copyMode, nil 2; 
with shadowStuff do OffsetRect( dragRect, -dx, -dy); 
end; (only if visible) 


(draw my object) 
CopyBits( pictureBits, offScreenBits, 
pictureBits.bounds,dragRect,srcCopy, thePictureRgn); 


{update what was on there plus the new position for 
the object) 
UnionRect( dragRect, lastRect, updateRect ); 
(include the shadow’s rectangle} 
1f shedowStuff .visible 
then begin 
with shadowStuff do OffsetRect( dragRect, dx, dy 2; 
UnionRect( dragRect, updateRect, updateRect ); 
with shadowStuff do 
OffeetRect( dragRect, -dx, -dy ); 
end; (only if visible) 
(clip it all to the screen boundaries) 
if ern ы ts .bounds, updateRect ,updateRect) 
hen (); 
RectRgn( updateRegion, updateRect ); 
(wait for just the right moment} 
(i can’t see an improvement, can you?) 
{ synchCount := TickCount; 
repeat until TickCount ‹ synchCount; 
) {put it on the screen) 
CopyBits( offScreenBits, screenBits, 
updateRect, updateRect, srcCopy, nil ); 
(restore bits underneath the picture) 
(remove any part of dragRect which is off the screen) 
if rede dragRect, screenB i ts .bounds, updateRect) 
en 0); 
(use а home’d rectangle for underBits) 
otherUpdateRect := updateRect; 
with otherUpdateRect do 
Of fSetRect( otherUpdateRect, -left, -top ); 
CopyBits( underBits, offScreenBits, 
otherUpdateRect, updateRect, srcCopy, nil ); 
{remember what parts of screenBits need to be fixed for 
next time) 
lastRect := dragRect; 
(restore bits underneath the shadow} 
if shadowStuff .visible 
then begin 
ye е г do OffsetRect( dragRect, dx, dy 2; 
clip it 
if SectRect(dragRect, screenBits.bounds, updateRect) 
then 0; 
(home it) 
otherUpdateRect := updateRect; 
with otherUpdateRect 
do OffSetRect(C otherUpdateRect, -left, -top 2; 
(shoot it) 
CopyBits( underShadowBits, offScreenBits, 
otherUpdateRect, updateRect, srcCopy, nil ); 
(add to parts of screenBits to be fixed for next time} 
UntonRect( lastRect, dragRect, lastRect ); 
with shadowStuff 
do OffsetRect( dragRect, -dx, -dy ); 
end; (only if shadow visible) 


end; (with dregStuff^^) 
HUnlock( HandleC dragStuff )); 
SetPort( oldPort ); 

end; (DregItTo) 


procedure DisposeDraggebleC dragStuff : DregHendle ); 
begin (tidy up) 
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if dragStuff € nil then begin 
HLock( HandleC dragStuff ) ); 
with dragStuff** do 
begin 
1f pictureBits.baseAddr € nil 
then DisposPtr( pictureBits.baseAddr ); 
1f underBits.baseAddr <> nil 
then DisposPtr( underBits.baseAddr ); 
1f underShadowBits.baseAddr € nil 
then DisposPtr( underShadowBits.baseAddr ); 
1f shedowBits.baseAddr © nil 
then DisposPtr( shadowBits.baseAddr ); 
1f offScreenBits.baseAddr € nil 
then CopyBitsC offScreenBits, screenBits, 
offScreenBits.bounds, screenBits.bounds, 
srcCopy, nil 2; 
if thePictureRgn o nil 
then DisposHandle( Handle(thePictureRgn) ); 
1f shadowRegion € nil 
then DisposHandle( HandleCshadowRegion) ); 
end; (with dragStuff) 
HUnlock С HandleC dregStuff ) ); 
DisposHandle( HendleC dragStuff ) ); 
end; (dragStuff © nil) 
end; (DisposeDraggable) 


procedure UpdateOffScreen С — dragStuff : DragHandle; 
Procedure drawProc ); 

begin 

GetPort( oldPort ); 

SetPort(C offPort ); 

SetPortBits( offScreenBits ); 

drewProc; 

SetPort( oldPort ); 
end; (UpdateOffScreen) 


procedure CloseDrag С disposeBitMap : boolean ); 
begin 
if offPort © nil then 
begin 
ClosePort( offPort ); 
DisposPtr( PointerCoffPort) ); 
end; 
if updateRegion © nil 
then DisposHandleC HendleCupdateRegion) ); 
1f disposeBitMap then 
1f offscreenBits.baseAddr © nil 
then DisposPtr( offScreenBits.baseAddr ); 
end; (CloseDrag) 


END. (unit Drag) 


program Fish; 
($0*) {put in debug names} 
($R*) (range checking on) 
($0V*) (overflow checking on) 
($N*) (pass routine names to linker) 
USES ($LOAD pinterfaces dump) 
МетТуреѕ , QuickDrew, OsIntf ,PesL ibIntf , ToolIntf, 
PackIntf, IntEnv, CursorCt1, 
($LOAD) 
($U UDrag.p} DragManager ; 


var 
myPic : PicHandle; 
myRect : Rect; 
wPort: GrafPtr; 
whichPict, 
x,y,xinc,yinc : integer; 
xyPt, lastXYPt : point; 
myEventRecord : EventRecord; 
lestCount : longint; 


myDragStuff : DragHandle; 
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procedure SwimItAround; 
const 
CapsLockBit = 10; 
var 
hOffset : integer; 
mousingRgn : RgnHendle; 
mousePt: Point; 
begin 
with shadowStuff do 
begin dx := Ø; dy := Ø; visible := false; end; 
with myPic** .picFrame do 
SetPt( lastXYPt, left-right, screenBits.bounds.bottom- 
Cbottom-top) div 2 ); 
xyPt := lastXYPt; 
hOffset := 2; 
mousingRgn := NewRgn; 
CopyRgn( myDregStuf f^^ .thePictureRgn, mousingRgn ); 
OffsetRgn( mousingRgn, -mousingRgn^^ .rgnBBox. left, 
-mous ingRgn*^ ^ .rgnBBox. top); 
OffsetRgn( mousingRgn, xyPt.h, xyPt.v 2; 
repeat 
1f button then 
begin 
GetMouse( nousePt ); 
LocalToGlobal( mousePt ); 
1f PtInRgnC mousePt, mousingRgn) 
then hOffset := 20; 


xyPt.h := xyPt.h + hOffset; 

XyPt.v := xyPt.v + (Random div 30000); 

OffsetRgn( mousingRgn, -mousingRgn^*^ .rgnBBox . left, 
mous ingRgn^ ^ .ngnBBox . top); 

OffsetRgn( mousingRgn, xyPt.h, xyPt.v 2; 


DragItTo(C myDragStuff, xyPt, false ); 

lastXYPt := xyPt; 

(allow for FKEY access and give DAs and such time) 

1f GetNextEvent( keyDownMesk, myEventRecord ) 

then (do nothing); 

SysteaTask; 
until xyPt.h > screenBits.bounds.right 

+ myPic**.picFrame.right-myPic** .picFrame. left; 
end; (dragitaround) 


begin(nain) 
InitGraf (@thePort); 


(standalones need to init windows, but tools shouldn't) 
if IEStendalone then Init¥indows; 


GetWMgrPort( wPort ); 
SetPort( wPort ); 
ClipRect( screenBits.bounds ); 


if not InitDrag( nil > then exit Fish ); 


myPic := GetPicture( 197); 
if myPic = nil then 
begin SysBeep(1); exit(Fish); end; 
(change up the default shadow stuff) 
with shadowStuff do 
begin 
thePattern := gray; 
copyMode := SrcOr; 
end; 


1f not NewDraggable( myPic, nil, nil, myDragStuff ) 
then exit(Fish); 

SwimItAround; 

DisposeDraggable( myDragStuff ); 

ReleaseResource( Handle( myPic 2); 
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CloseDrag( true 2; 
FlushEvents( everyEvent, 0 ); 


end. 


program DragExample 1; 

($0*) (put in debug names) 

($R*) (range checking on) 

($0V*) (overflow checking оп) 

($N*) (pass routine names to linker) 
USES ($LOAD 


pinterfaces.dump}MemTypes, QuickDraw, OsIntf ,Раѕі. ibIntf , ToolIntf, 


Pack Intf , IntEnv, CursorCt1, 
($LOAD) 
($U UDrag.p} DragManager; 


var 
myPic : PicHandle; 
nyRect : Rect; 
wPort: GrafPtr; 
whichPict, 
x,y,xinc,yine : integer; 
xyPt, lastxYPt : point; 
myEventRecord : EventRecord; 
lestCount : longint; 


myDregStuff : DregHendle; 


procedure Drag! tAround; 
const 
CapsLockBit = 19; 


begin 
SetPt( lastXYPt, -1, -1 ); 
repeat 

GetMouse(xyPt); 
(if the movement is far enough, the next line of code 
(commented out) can be used to make the image persist long 
enough that it doesn’t appear ghostly. On the other hand, if 
the movement is very small, the image generally looks nice and 
solid and does not benefit from delays.) 

(if TickCount >= lestCount + 2 then) 

1f not EqualPtC xyPt, lastXYPt) then 


begin 
(if CepsLockKey, don’t show the shadow, else show it) 
17 EventAvatiC2, myEventRecord) then (twiddle); 
1f BTSTCmyEventRecord.modifiers, CapsLockBit) 
then with shadowStuff do 
begin dx := Ø; dy := Ø; visible := false; end 
else with shadowStuff do 
begin 
dx := xyPt.h div 8 - 32; 
dy := xyPt.v div 8 - 20; 
visible := true; 
end; 


DregItToC myDragStuff, xyPt, true ); 


lestXYPt := xyPt; 
TastCount := TickCount; 
end; 
(allow for FKEY access and give DAs and such time) 
if GetNextEvent( keyDownMask, myEventRecord ) 
then (do nothing); 
SystenTask; 
until button; 
repeat until not button; 
end; (dragiteround) 


begin(main} 
InitGraf(é@thePort); 


(standalones need to init windows, but tools shouldn't) 
17 IEStandalone then InitWindows; 
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GetWMgrPort( wPort ); 
SetPort( wPort ); 

ClipRect( screenBits.bounds 2; 
InitCursor; 

HideCursor; 


1f not InitDrag( nil 2 then exit DregExemplel ); 


for whichPict := 1 to CountResources( 'PICT^) do 
begin 
myPic :- PicHandle(GetIndResource( ‘PICT’, whichPict)); 
1f myPic = nil then 
begin SysBeepC 1); exitCDregExemple1); end; 
(change up the default shadow stuff) 
with shadowStuff do 
begin 
thePattern := gray; 
copyMode := 5гс0г; 
end; 


if not NewDraggableC myPic, nil, nil, myDragStuff ) 
then exit(DragExample 1); 
DragI tAround; 
DisposeDraggable(€ myDragStuff ); 
Р ReleaseResource( Handle( myPic 2); 
end; 


CloseDrag( true ); 
FlushEvents( everyEvent, 0 ); 


end. 


program ОгәдЕхатр1е2; 
($0*) (put in debug names) 
($R+} (гапде checking on) 
($0V*) (overflow checking on) 
($N*) (pass routine names to linker) 
USES ($LOAD pinterfaces .dump) 
MemTypes, QuickDraw,OsIntf ,PasLibIntf, ToolIntf, 
PackIntf , IntEnv,CursorCt1, 
($L0AD) 
($0 UDrag.p) DragManager ; 
var 
myPic : PicHendle; 
myRect : Rect; 
wPort: GrafPtr; 
whichPict, 
x,y,xinc,yine : integer; 
xyPt, lastXYPt : point; 
myEventRecord : EventRecord; 
lestCount : longint; 
myDragStuff : DragHandle; 


procedure Debugger; ( turned off for now 
INLINE $A9FF;) 
begin 

(stub) 

end; 


procedure BounceItAround; 
begin 
бе tMouse(xyPt); 
xinc := xyPt.h; 
yinc := xyPt.v; 
(starting position) 
y := (screenBits.bounds .right-screenBi ts .bounds . left) 
div 2; 
x := (screenBits.bounds.bottom - screenBits.bounds. top) 
div 2; 
(changes don^t occur until the focal point moves, so 
this makes sure it’s drawn the first time.) 
SetPt(lastXYPt, -100, -100); 
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repeat 
Ge tMouse(xyPt); 
(use the cursor position to set the velocity of the 
bouncing picture. It doesn’t change the direction, 
just the speed.) 
if xinc > 0 then xinc : 
if yinc > 0 then yinc : 
(move the focal point} 
X := x + xinc; 
y := у + уіпс; 
(keep it on the screen and bounce off the edges if needed) 
with screenBits.bounds do 
if y < top then 
begin y := top; yinc := -yinc; end 
else if y › bottom then 
begin y := bottom; yinc := -yinc; end; 
with screenBits.bounds do 
if х < left then 
begin x := left; xinc := -xinc; end 
else if x» right then 
begin x := right; xinc := -xinc; end; 
SetPtC xyPt, x, y ); 
(if the movement is far enough, the next line of code (com- 
mented out) cen be used to meke the image persist long enough 
that it doesn’t appear ghostly. On the other hand, if the 
movement is very small, the image generally looks nice and 
solid and does not benefit from delays.) 
(1f TickCount >= lastCount + 2 then) 
if not EqualPtC xyPt, lastxYPt) then 
begin 
(if CapsLockKey, don’t show the shadow, else show it) 
1f EventAvail(@, myEventRecord) then (twiddle); 
1f BISTCmyEventRecord.modifiers, 10) 
then with shadowStuff do 
begin dx := 2; dy := 0; visible := false; end 
else with shadowStuff do 
begin 
dx := xyPt.h div 8 - 32; 
dy := xyPt.v div 8 - 20; 
visible := true; 
end; 
DragItToC myDragStuff, xyPt, true ); 
TastXYPt := xyPt; 
lestCount := TickCount; 


xyPt.h else xinc := -xyPt.h; 
xyPt.v else yinc := -xyPt.v; 
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end; 
(allow for FKEY access end give DAs end such time) 
if GetNextEvent( keyDownMask, myEventRecord ) 
then (do nothing); 
SystenTask; 
until button; 
repeat until not button; 
end; (bouncei taround) 


begin(nain) 
IntitGraf(CéthePort?; 
(stendalones need to init windows, but tools shouldn't) 
1f IEStendalone then InitWindows; 
GetWNgrPort( wPort ); 
SetPort( wPort ); 
ClipRect( screenBits.bounds ); 
InitCursor; 
if not InitDrag( nil ) then exitC DragExample2 ); 
for whichPict := 1 to CountResources( ‘PICT’) do 
begin 
myPic := PicHandle(GetIndResource( ‘PICT’, whichPict)); 
if myPic = nil then 
begin SysBeep(1); exit(DragExample2); end; 

1f not NewDraggable( myPic, nil, nil, myDragStuff ) 
then exit(DragExample2); 

Bounce! tAround; 

DisposeDreggebleC myDragStuff ); 

( Use this code to take a look at pictures that 
display some behavior you don’t understand.) 
repeat until not button; 
repeat until button; 

FillRect( screenBits.bounds, white ); 
HLock( HandleC myPic )); 

DrawPictureC myPic, myPic**.picFrame ); 

myRect := myPic^^.picFreme; 

with myRect do 

OffsetRect( myRect, -left, -top ); 

DrawPicture( myPic, myRect ); 

HUnlock( Handle( myPic 22; 


ReleaseResource( Handle? nyPic )); 


end; v 
CloseDrag( true 2; 2м, 
end. 
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Pascal Procedures 


Library Manager Cures HFS Brain Damage 


"File Not Found!" 

How many times have you run a compiler or linker program 
only to have it come up and say “file not found" after which the 
program returns you to the Finder or worse, crashes the system. 
Then you have to find the mystery file the program wants, then 
figure out which folder the program expects to find it, and try to 
coerce the program into locating it. Programs that make you do 
this are HFS brain damaged. They can't find their way out of a 
paper bag. Microsoft is notorious for products which either can't 
find files (MS Basic) or require files to be in certain folders (MS 
Word), or die when a file cannot be found (MS Fortran). While 
Apple provided an elegant way for applications to allow the user 
to find a document, via the standard file dialog, no thought was 
given to those types of programs which must locate a library or 
reference file that is either not known to the user, or not directly 
related to a user created document, but which is vital for the 
program to function. Think Technologies with their Lightspeed 
C and Pascal was one of the first companies to market a truly HFS 
smart compiler. If LS Pascal can't find a file it needs, it asks the 
user to find it! What could be simpler or more straight forward? 
Who needs path managers? Who needs Finder DA's? Who needs 
path name scripts? In this article I show how you can use this 
technique to make your applications HFS smart, by putting up a 
standard file dialog if a library file cannot be found. Once the user 
finds the file, it's location is remembered in a resource so the 
dialog does not have to be repeated unless the file is moved or 
renamed. Why should a program (like 4th Dimension) prevent 
you from moving or renaming your files? Even though HFS has 
been with us for over a year and a half, many developers are still 
working around it, not with it. It'S time to make our programs 
HFS friendly and this article will show you how to do it. 

Library Manager Tracks Your Files 

As Macintosh programs become smarter and heftier, the need 
increases to maintain libraries of information that are external to 
the application itself. Because I am currently developing an 
application that requires three separate kinds of open file lists, I 
spent some time putting together what I call a“Library Manager" 
to help keep things straight. The classic example of a file you 
would use the library manager to track and open is the "diction- 
агу”, a library type that may include a whole list of generic, 
technical, and user-defined files that should be opened automati- 
cally without unnecessary user intervention and without the user 
having to place them in either (a) the same folder with the 
application or (b) the System Folder which is beginning to get 
cluttered...; (Acius, are you paying attention?) 

Our application is a demonstration of how an application can 
be designed to keep track of and locate files without crashing, 
quiting or forcing the user to place or name files in a certain way. 
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The Make My Day File was not opened 
because the file could not be found. 
Look for a library to open? 


Fig. 1 Let the user find it! 


The demo application makes calls to what I have named the 
Library Manager, a unit of LS Pascal routines which provide the 
support for creating HFS friendly programs. By adding this 
Library Manager unit to your own projects, your applications can 
be made as HFS friendly as the products from Think Technolo- 
gies. 
Installing Library Manager 

TheLibrary Manager keeps track of application files using an 
application defined resource of type LMIR, Library Manager 
Information Resource. A separate LMIR resource is created for 
each file for which the application needs to know the where- 
abouts. The LMIR is shown defined below: 
LMIR = RECORD  (Librery Menager Info Record) 


rsrcID : integer; 
volname :str31; 


vRef : integer; 
hfsvolume : boolean; 
DirID : Longint; 
filename : str63; 


fRefNum : integer; 
next, prev :LnirHdl; 
FTyp : integer; 
RecsOnF ile, CurRec : 
changed :boolean; 
Status : (Open, Closed, NotFound); 


D; 


integer; 


Once the Library Manager code is added toan existing project 
and the routine OpenLib is called, the Manager is self-initializ- 
ing. When а call is made to OpenLib for a МІК resource that 
does not exist, OpenLib creates the resource and adds it to the 
current resource file. A typical setup routine is shown below that 
makes this call to OpenLib: 

PROCEDURE SetUpThings; 


GIN 
OpenLib(TopFile, ‘Application Default Library’); 
(When program boots) 
OpenLinkedLibCTopF ile, ‘User Default Library’); 
(When program boots) 
END; 
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When OpenLib is called, if the appropriate LMIR resource 
does not exist or if the file the resource points to has been moved 
(or renamed, is unmounted, etc.) the user is prompted and 
allowed (not forced) to find or create a new library file. The 


message displayed to the user tells him the exact nature of the 


problem: The volume isn't mounted, the file can't be found, the 
fileis already open for read/write, etc. All of the possible HFS file 
problems are clearly trapped and displayed here. No more "call 
Aldus, error number 1234" stuff. 

For the developer, this means that once the library manager is 
added to his code and calls are made to OpenL ib, he can 

(1) Ignore prompts to find or create the library (until ready) 

(2) Create a new library file someplace (and not be bothered 

again) 

(3) Tell the program where he has moved the library file to 

(4) Mount the volume that the library file is on, if that is the 

problem. 

Note that moving the application won't disturb the Library 
Manager's ability to find a file, only tampering with the location 
or name of the library file itself. 

Lotsa Lovely Linked Lists of Libraries 

When calls are made to OpenLinkedL ib additional library 
files are linked using а circular forward and backward chain. As 
many separate lists of files as desired can be created with 
OpenLib, and as many files can be added to any particular list 
with OpenLinkedLib as the application demands. Thus you сап 
support a whole bunch of related files that must be opened at run 
time. 

The linked lists allow you to search through all files of a given 
library type by using a loop along the lines of: 

next := top; 

repeat 

IFoundit := YourSearchRoutine(next); 


next : next^^.next; 
until IFoundlt or (next = top); 


Another agreeable aspect of linked lists is that the library 
manager requires you to define only one (global?) variable per 
list: the handle to the top item of the list. 

Removing Files from a List 

Call RemoveLib to close an open library file and remove it 
from the list. Note that RemoveL ib always returns a valid handle 
if there are still any open libraries in the list. This allows you to 
remove even the “top” item from a library list, because Remov- 
eLib automatically replaces it with a *new" top. If you are 
removing the top item from the list, you should reference it 
specifically when you pass it to RemoveL ib. 

RemoveLib(Top); 

( that is, whatever variable name you passed 
to Open Lib originally ) 


not 
RemoveLib(next); 


RemoveLib(next^^.next); 
if there's a chance that next or next^^.next = Top. 


A file that has been removed with RemoveLib can be reo- 
pened with OpenLinkedLib or OpenL ib. 
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RemoveLib checks whether the changed field of the Library 
Manager Record is true. If so, it calls HandleChanges. Han- 
dleChanges does nothing! It is just included to give you the 
general idea. | 

Closing АП Open Files In a List 

At exit time, call CloseLibList for each library list that is 
open. It will close all open files in a list, by successive calls to 
RemoveLib, until the list is empty. 

Access is by Resource Name, not Resource ID 

As you will see when you examine OpenLib and GetLibRe- 
source, the library manager accesses files by a descriptive 
resource name rather than by resource ID. 

The Library Manager was developed to work in conjunction 
with routines that will extend menus by allowing the user to 
create new menu items and associate those items with individual 
files. If you are allowing the user to extend libraries in this (or 
some similar) way, you should call GetLibResource before you 
call OpenLinkedLib or OpenLib to make sure that a “new” 
library descriptive name does not already exist. It is your 
responsibility to make sure that the names used to access re- 
Sources are unique, the Library Manager does not check. 

Library File Type 

When the Library Manager creates a new file it assigns it type 
LMIR. Likewise, when you look for a file using the standard file 
dialog, it will only show you files of type LMIR. This can be 
modified according to your application's requirements. 

The Nitty Gritty of Tracking Things 

The routines work with new roms or old roms, HFS or MFS 
volumes (or any mixture); 

In order to actually install a LMIR resource, the user (or 
developer) is guided by the application through the Standard File 
Package. 

In order to maintain compatibility between HFS and MFS, 
Apple fixed things so that the Standard File returns a working 
directory number instead of a volume reference number. The 
important thing about working directory numbers is that they are 
created on the fly and they are strictly temporary and relative to 
a particular session. 

What is needed is to turn the working directory number into 
a Volume Name andaDirectory ID. The procedure that does this 
is GetPathInfo. When a file needs to be opened, the procedure 
OpenWD creates a new working directory for the file from this 
information. This new working directory number is then passed 
to FSOpen as the volume reference. If the volume is MFS and 
not HFS, OpenWD simply returns the volume number instead of 
a working directory and FSOpen is still happy. 

File IO on Open Files 

The File reference number for an opened file is stored in the 
LMIR record. There are also fields to maintain information on 
file type, total records, current record number. You can, of 
course, add other fields to your LMIR definition (or remove some 
of mine). 

The Program Lib Mgr Demo.. 

...does a minimum three things 

1) It looks for mythical "application default" and “user 

default” library files. 
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2) Ittells you the status of the files: Opened, Closed, 
NotFound. 

3) It waits for you to press the mouse button and then closes 

the files (if any are open). 

The first time you run the program it will prompt you to find 
or create the two files mentioned above. If you satisfy these 
requests, the next time it will simply open the files without your 
intervention. To see how the program handles various problems, 
try moving, deleting, renaming, dismounting one or both files 
and rerunning the program. 

The program was developed in LightSpeed Pascal. If you are 
using something other than LightSpeed, remove the DisplayMsg 
procedure and use the DisplayMsg2 procedure. 

The only resource that the file needs is an alert dialog, ID = 
301 and its associated item list. If you run the program in 
Lightspeed project mode, make sure you use a project resource 
file, or the "current resource file" the LMIR resources will be 
added to will be your system file! 

Onelast thing: this code will need to be modifted to fit your 
particular needs. The Library Manager I’ve presented is meant 
to be suggestive, not definitive. I'm sure that you will have to 
make changes for your own application environment(s). Butit 
will give you a good base to work from. Toward this end, direct 
access to procedures not specifically mentioned in this article is 
provided in the interface portion of the LibMgr unit. 

Acknowledgements 

The HFSRunning and NewRoms came from a utilities 
package developed by David O'Rourke that is in the public 
domain. Thanks, Dave! 

And so, if there are no further questions, let's break for lunch. 


UNIT LibMgr; 

INTERFACE 

USES 
Rom85, HFS; 

PE 
StenderdType = (StandardGet, StandardPut); 
Outcome = (Success, Error, Cancellation); 
str63 = STRING(63]; 
str3i = STRINGI311; 
str8ð = STRING(80]; 


LnirPtr 
ітігНа1 


= “Lmir; 

= *LmirPtr; 

LMIR = RECORD (Library Manager Info Record) 
rsrcID : integer; 
volneme : str31; 
vRef : integer; 
hfsvolume : boolean; 
DirID : Longint; 
filename : str63; 
fRefNum : integer; 
next, prev : LmirHdl; 
FTyp : integer; 
RecsOnFile, CurRec : 
changed : boolean; 
Status : (Open, Closed, NotFound); 

END; 


PROCEDURE GetPathInfo CvRefNum : integer; 
VAR rootVol : Str31; 
VAR hfsFlag : boolean; 


integer; 
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VAR WDirID : longint); 


FUNCTION OpenWD CVAR vRefNum : integer; 

DirID : longint) : OSErr; 
PROCEDURE OpenLib (VAR whichLib : LmirHd]; 

itsName : str255); 
PROCEDURE OpenL inkedLib (LinkTo : LmirHdl; 
ResNeme : str255); 
FUNCTION CreateLib (VAR newLib : LmirHdl) : boolean; 
FUNCTION FindLib (VAR theLib : LmirHdl) : boolean; 
PROCEDURE RemoveLib (VAR whichFile : LmirHdl); 
(Close file and remove from list of open libreries) 

PROCEDURE CloseLibList (Top : LmirHd1); 
(Close 811 open libraries in a given list and empty list) 
FUNCTION StenderdFile CopCode : StandardType; 

oldName : Str255; 

fType : OSType; 

VAR vRef : integer) : str63; 
PROCEDURE GetLibraryResource (VAR theLibrary : LmirHd; 


ResourceName : str255); 
IMPLEMENTATION 
FUNCTION HFSRunning : boolean; 
CONST 
FSFCBLen = $3F6; 
VAR 
HFS : “INTEGER; 
BEGIN 


HFS := POINTERCFSFCBLen); 
HFSRunning := CHFS* » 0); 


Ф 


FUNCTION NewRoms : boolean; 


CONST 
NewRomsID = 117; 
VAR 
RomVersion, Machine : INTEGER; 
BEGI 


EnvironsCRomVersion, Machine); 
NewRoms := RomVersion >= NewRomsID; 
END; 
FUNCTION GetErrorMsg (Result : OSErr) : str80; 
BEGIN 
Result := abs(Result); 
CASE Result OF 


GetErrorMsg := ‘the file directory is full. ‘; 
GetErrorMsg := “ӘТІ allocation blocks on the volume ere 
full. '; 

GetErrorMsg := ‘the specified volume is not mounted. “; 
GetErrorMsg := ‘there was an unspecified 1/0 Error. ”; 
GetErrorMsg := ‘the file name or volume name is bad 


(perhaps zero-length). ', 


GetErrorMsg := ‘logical end-of-file was reached unexpetedly 
during read operation. °; 


GetErrorMsg := “ап attempt was made to position before 
start of file. '; 


GetErrorMsg := ‘too many ere files open. ', 
GetErrorMsg := ‘the file could not be found. '; 
GetErrorMsg := ‘the volume is locked by a hardware setting. 
e. 

é 
GetErrorMsg := ‘the file is locked’; 
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GetErrorMsg := ‘the volume is locked by а software flag. 
f. 


д 


GetErrorMsg := ‘the file is already in use. ', 


GetErrorMsg := ‘a file with the specified name exists end 
cannot be overwritten. ‘; 


GetErrorMsg := ‘the file is already open for read/write. 
It cannot be reopened. '; 


GetErrorMsg :* ‘no volume was specified and there is no 
default volume. '; 


GetErrorWsg := “а non-existent path was specified. ', 


GetErrorMsg := ‘there was an error finding current position 
in file. ‘; 


GetErrorMsg := ‘the specified volume is not on-line. ', 


GetErrorMsg := ‘there was an attempt to open a locked f ile 
for writing. ', 


GetErrorMsg := ‘there was an attempt to mount an already 
mounted volume. ‘; 


GetErrorMsg := ‘the specified drive number is not mounted. 
е. 


д 


GetErrorMsg := ‘the volume lacks Macintosh-format direc- 
tory. ^'; 


GetErrorMsg := ‘there was an external file system error. 
e. 


) 


GetErrorlsg := ‘there was a problem during rename. ', 


GetErrorMsg := ‘the master directory block is bed; this 
volume must be reinitialized. ‘; 


GetErrorMsg := ‘the read/write permission of the file/ 
folder does not allow writing . '; 
108 : 
GetErrorMsg := ‘there is insufficient application memory. 
f. 
220 : 
GetErrorMsg := ‘the directory could not be found. '; 
121 


GetErrorMsg := “(00 many working directories are open. “; 
2 . 


GetErrorMsg := ‘a folder cannot be placed in its own 
subfolder. ‘; 
123 : 
GetErrorMsg := ‘an attempt was made to do hierarchical 
operations on a nonhierarchical volume. ', 
7 . 


GetErrorMsg := ‘there was an internal file system error. 
e. 


PROCEDURE UpdateResource (vanilla : handle); 
BEGIN 


ChangedResource(vani 11a); 
Wr iteResource(vanilla); 


Ф 


PROCEDURE IOCheck CresultCode : OSErr); 
VAR 
ignore : INTEGER; 


errorString : Str255; 
BEGIN 
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IF resultCode <> NoErr THEN 
BEGIN 


NumToStr ing(resultCode, errorString); 
РагапТех(С ‘Macintosh Error 8”, errorString, ': ', 
Ge tErrorMsg(resul tCode 2); 
InitCursor ; 
ignore := StopAlertC305, NIL); 
END 


FUNCTION StanderdF ile; 
(opCode : StenderdType; oldName : 
${г255; fType : OSType; ) 
(ver vRef : integer) : str63 } 
VAR 

where : Point; 

reply : SFReply; 

textType : SFTypelL ist; 


: ғ 
textType(0] := fType; 
reply.vRefNum := vRef; 
IF opCode = StandardGet THEN 
SFGetFileCwhere, ‘Select Application to Launch’, 
NIL, 1, textType, NIL, reply) 
ELSE 


SFPutFileCwhere, “”, oldName, NIL, reply); 
WITH reply DO 
IF NOT good THEN 
StendardFile := °’ 
ELSE 
BEGIN 
StandardFile := fName; 
vRef := vRefNum 
END 


PROCEDURE HandleChanges (changedFile : LmirHdl); 
BEGIN 
(А boolean field in the LMIR can be set if your change 
records in memory but you do not immediately write them out to 
the file... Then put whatever routines you need to handle 
aries to records inmemory here) 
ND; 


PROCEDURE RenoveL ib; (ver whichFile : LmirHd1);) 
VAR 


ReturnValidHdl : LmirHdl; 
BEGIN 
IF whichFile^^.chenged THEN 
HendleChanges(whichF ile); 
IF whichFile**.status = Open THEN 
T0Check(FSCloseCwhichFile**.fRefNum)); 
ReturnValidHd] := whichFile** next; 
whichFile^^.prev^^.next := whichFile** next; 
whichFile**.next**.prev := whichFile** prev; 
whichFile**.status := Closed; 
UpdeteResourceChandleCwhichF i 1e22; 
ReleeseResourceChandle(CwhichF 11е) ); 
whichFile := ReturnValidHdl; 
END; 


br is CloseLibList; (Top : LmirHdl; ) 
À 
next : LmirHd1; 
next := Top^^.next; 
AT 
Removel ib(next); 
UNTIL next = Top; 


Removel ibCTop); 
END; 
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FUNCTION OpenWD; (var vREfNum : integer; ) 
( DirID : longint) ) 
( : OSErr; ) 
VAR 
bik : WDPBRec; 
Result : OSErr; 
GIN 


blk.ioCompletion :- NIL; 
Result := PBGetVolC@bik, false); 
(this just sets ioWDProcID to whatever...) 
IF Result = NoErr THEN 
BEGIN 
WITH bik DO 
BEGIN 
ioNemePtr := NIL; 
ioVREfNum := vRefNum; 
ioWDDirID := DirID; 


END; 
Result := PBOPenWDCOeblk, false); 
vRefNum := blk. ioVRefNum; 
END; 
OpenWD := Result; 
END; 


PROCEDURE GetPethInfo; ( vRefNum : integer; ) 
( ver rootVol : Str31; Ў 
( var hfsFlag : boolean 2;) 
(ver WDirID : longint;) 
VAR 
blk : CInfoPBRec; 
volBlk : HParamBlockRec; 
dirname : str255; 
BEGIN 
rootVol := °’; 
WITH volBlk DO 
BEGIN 
ioCompletion := NIL; 
ioNemePtr := @rootVol; 
ioVRefNum := vRefNum; 
ioVolindex := 0; 
ioVSigWord := 0; 
E ыны ИОА false)); 
ND; 
rootVol := Concat(rootVol, ':^5; 
hfsFlag := HFSRunning; 
IF hfsFlag THEN 
WITH blk DO 
BEGIN 
ioCompletion := NIL; 
dirname := °’; 
ioNamePtr := @dirname; 
ioVRefNum := vRefNum; 
ioFDirINdex := -1; 
ioDrDirID :- 0; 
IOCheckCPBGetCat INfoCGblk, false)); 
WDirId := ioDrDirID; 
END; 
END; 


FUNCTION CreateLib; (newLib : LmirHd]; prompt : boolean) : 
boolean) 
CONST 
null =“, 
VAR 
Result : OSERR; 
EGIN 


CreateLib := False; 
WITH newLib** DO 
BEGIN 
Filename := StandardFile(StandardPut, ‘Make My Day’, 
‘LMIR’, vref); 
IF Filename <> null THEN 


BEGIN 
Result := Create(FileNeme, vRef, ‘DAVE’, ‘LMIR’); 


© The Essential MacTutor, Vol. 3 


IF Result = NoErr THEN 


BEGIN 

GetPathInfoCvRef, volNeme, hfsvolume, Dir ID); 
CreateLib := True; 
END 


LSE 
10Check (Result); 
END 
END 
END; 


FUNCTION UserWantsToCreateLib : boolean; 
CONST 


yes = 1; 
VAR 
pi, p2, p3, p4 : str80; 
Response : integer; 
BEGIN 
‘Create a new library? '; 
бә. 
д 
(sd. 


7 
e). 


4: ; 
PeremText(p1, p2, p3, p4); 
InitCursor; 

Response := CeutionAlertC301, NIL); 
IF (Response = Yes) THEN 
UserWantsToCreateLib := true 


оо 
со 
пип ои 


UserWantsToCreateLib := false; 
END; 


FUNCTION FindLib; (ver : theLib : LmirHd]; prompt : 
boolean; result : OSErr) : boolean) 
CONST 
null =“; 
VAR 
dummy : OSERR; 
ee : integer; 


FindLib := False; 
WITH theLib** DO 
BEGIN 
Filename := StenderdFileCStenderdGet, '^, ‘LMIR’, vref); 
IF FileName © null THEN 
BEGIN 
GetPathInfo(vRef, volNeme, hfsvolume, Dir ID); 
FindLib := True; 


END; 
END; 
END; 
FUNCTION UserWantsToF indLib CwhichLib : LmirHdl; 
Reference : Str255; 
errorCode : OSErr) : boolean; 
CONST 
yes = 1, 
VAR 
pl, p2, p3, p4 : str80; 
Response : integer; 
UseName : str63; 
BEGIN 


IF whichLib^^.fileneme = '^ THEN 
UseName := Reference 


UseName := whichLib^^.filename; 
pi := ConCatC'The ”, UseName, ' File was not opened 


because '); 


= GetErrorMsg(ErrorCode); 

p3 := ‘Look for a library to open? ‘; 
p4 = ''; 

PerenText(p1, p2, p3, p4); 

InitCursor; 

Response := CeutionAlertC301, NIL); 
IF (Response = Yes) THEN 
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UserWentsToF indLib := true 
E 


UserWantsToF indLib := false; 
END; 


PROCEDURE GetUserHelp (whichLibrery : LmirHdl; 
ReferredToAs : str255; 
ErrMsg : OSErr); 
VAR 
Intent, Attainment, Cancelled : boolean; 
IN 


whichLibrary**.status := NotFound; 
(Guilty until proven innocent) 
HLockCHandleCwhichL ibrary)); 


IF UserWantsToF indLibCwhichLibrary, ReferredToAs, 
ErrMsg) THEN 
IF FindLibCwhichLibrary) THEN 
BEGIN 
UpdateResource(HandleCwhichLibrary)); 
whichLibrary**.status := Closed; 
END; 
IF whichLibrery^^.stetus = NotFound THEN 
(User chose not to Open Existing File) 
REPEAT 
Intent := UserWentsToCreateL ib; 
IF Intent THEN 
Attainment := CreateLib(whichLibrary); 
IF Intent AND Attainment THEN 
BEGIN 
UpdateResourceCHandleCwhichL ibrary)); 
whichLibrary**.status := Closed; 
END; 
UNTIL (NOT Intent? OR CAttainment); 
HUnLockCHandleCwhichLibrary)); 
END; 


FUNCTION LibOpenedSuccessfully CLibToOpen : LmirHdl; VAR 
Result : OSErr) : boolean; 
VAR 


fRefNum : integer; 
SeveCurrentvol : integer; 
Success : boolean; 
Ignore : OSErr; 
BEGIN 
Success := False; 
Ignore := GetVolCNIL, SeveCurrentVo1); 
(Save the defeult volume ) 
MoveHHICHandleCL ibToOpen2); 
HLockCHandleCL ibToOpen)); 
WITH LibToOpen** DO 
BEGIN 
result := SetVolC@volname, 2); 
(Is the root volume mounted?) 
IF Result = NoErr THEN 
result := GetVol(NIL, vRef); 
(Then make it default ) 
IF (Result = NoErr) AND hfsVolume THEN 
(Open the Working Directory) 
Result := OpenWDCvRef , бігі0); 
IF Result = NoErr THEN 
(Vref is now correct whether HFS or MFS) 
Result := FSOpen(f ileNeme, vRef, fRefNum); 
IF Result = NoErr THEN 
BEGIN 
Success := True; 
status := open; 
END; 
END; 
HUnLockCHandleCL ibToOpen2); 
LibOpenedSuccessfully := Success; 
Ignore := SetVolCNIL, SaveCurrentVol); 
(Restore the original default volume) 


PROCEDURE InitLibResource (VAR Lib : LmirHd1; 
LibNeme : str255); 


BEGIN 
Lib := LmirHdl(newHendle(SizeOf (міг 22); 
Lib^^.RsrcId := uniqueIDC'LMIR^); 

WITH Lib^^ DO 
BEGIN 
уе? := 0; 
RecsOnFile : 


RecsOnFile := 0; 
CurRec := 0; 
status := NotFound; 
changed := false; 


E • 
AddResource(HendleCL ib), ‘LMIR’, Lib**.RsrcID, LibName); 
END; 


PROCEDURE GetLibraryResource; (ver theLibrery : LmirHd]; 
ResourceName : str255) 
BEGIN 
IF NewRoms THEN 
theLibrary := LmirHdlCGet INamedResource( ‘LMIR’, Re- 
sourceName )) 
ELSE 
theLibrery := LmirHdlCGetNamedResourceC 'LMIR^, Re- 
sourceName )); 
END; 


da OpenLib; (ver whichLib : LmirHdl; itsNeme : str255) 
AR 
Result : OSErr; 
EGIN 


GetLibraryResource(whichLib, itsNeme); 
IF whichLib = NIL THEN 
InitLibResourceCwhichLib, itsName); 
(No resource even exists... Create one) 


(Potential Problem #1 - The resource was *just* created by 
бей ibrary) 
IF whichLib^^.status = NotFound THEN 
(А resource exists, but no file ) 
GetUserHelp(whichLib, itsName, 43); 
(Potential Problem 82 - The resource is there but the file 
couldn^t be opened) 
WHILE (whichLib^^.status = Closed) AND (NOT 
LibOpenedSuccessfully(whichLib, result?) DO 
GetUserHelp(whichLib, itsName, Result); 


(Note: if the user refuses to either look for or create a 
file, then status will be set to NotFound) 
(end the loop ends. Of course, the loop also ends if a file 
is opened successfully. 
whichLib^^.next := whichLib; 
whichLib^^.prev := whichLib; 
0; 


PROCEDURE OpenLinkedLib; (LinkTo : LmirHd!;) 
ResNeme : str255);) 
VAR 


nwLib : LnirHd1; 

BEGIN 
OpenLib(newLib, ResName); 
newLib^^.next :» LinkTo^^.next; 
LinkTo^^.next := newLib; 
newLib^^.prev := LinkTo; 
newLib**.next**.prev := newLib; 


END; 
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p2 := Concat(TopFile^^.next^^.fileneme, ^ is ‘, Statusix], 
er 
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p3 := ‘ 


D Make My Day 
PROCEDURE DisplayMsg; 
VAR 


D Make My Day 2 
Open 
Cancel 
next : LnirHdl; 


Fig. 2 Our demo puts up a standard file dialog cL, 


SetRect(newRect, 80, 40, 430, 2900); 
SetTextRect(newRect); 
ShowText; 


MacPasLib de | 
MacTraps IT TopF ile; 
ROMSSLib a RUN 


Rone next**.status); 


HFS ызы ae Я 
Library Ménagér next := next^^.next; 


A 
14; 


з 
Vv) 


œ HP™ 40-6 


p4 := ‘Would you like a nice cool glass of lemonade? ‘; 
PerenText(p1, p2, p3, p4); 


x := CautionAlert(381, NIL); 
END; 


Library Manager Project 


The File ‘, next**. filename, ' is ‘, 


i UNTIL next = topfile; 
gg ete Writeln(* Press mouse button to close files and 
"———————— fent! € PAX —————————' o exi t 7 ); 
ЕН пнаяапнааарнанааннна ннн © WHILE NOT button DO 
USSUUEEDUDUDUUUSEEEEEEUDUD А 
Fig. 3 Link Procedure END; 
PROCEDURE CloseThings; 
BEGIN 
PROGRAM LibMgrDemo; CloseL ibListCTopF ile); 
($I- Lightspeed Compiler Command) END; 
USES 
LibMgr; BEGIN 
VAR InitThings; 
TopFile : LmirHd!; SetUpThings; 
DispleyMsg; 
PROCEDURE InitThings; CloseThings; 
BEGIN . 
InitGraf(@thePort); (grafport for the screen) 
MoreMesters; 
MoreMasters; 
MoreMasters; LibMgrRsrc.Rel 
InitFonts; 
InitWindows; Type DITL 
InitMenus; 
TEInit; ,301 
InitDialogs(NIL); 3 
FlushEventsCeveryEvent, 2); з 1 
InitCursor ; Button Enabled 
END; 112 108 132 168 
Yes 
PROCEDURE SetUpThings; 
BEGIN * 2 
OpenLibCTopFile, ‘Application Default Library’); Button Enabled 
(When program boots) 112 246 132 306 
OpenL inkedL ibCTopFile, ‘User Default Library’); No 
(When program boots) 
END; * 3 
SteticText Enabled 
PROCEDURE DisplayMsg2; 9 69 104 337 
VAR ^9^1^2^3 
pl, p2, p3, p4 : str80; 
status : ARRAY[2..3] OF str80; Type ALRT 
x : integer; 3 
BEGIN 60 60 210 420 
Stetus(0] := ‘Open’; 301 
Status[1] := 'Closed'; CCCC 


Status[3] := ‘Not Found’; 
x := Ord(TopFile**.status); 

рі := ConcetCTopFile^^.filename, ‘ is ^, Status{x], '. ”; 
x := Ord(TopFile^^.next^^.status); 
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Macintosh П 


Hierarchical Menus 


MenuFun: Macintosh // Menu Manager 


Like most of the toolbox managers, the Menu Manager of the 
Macintosh // has undergone several enhancements and improve- 
ments. The Apple Menu is automatically multicolored (like the 
Apple logo) on any color monitor, while every portion of the 
menu bar and menus can be displayed in any RGB color by the 
program. Menus can now include Hierarchical Menus. These 
Hierarchical menus (sometimes called Cascading Menus or 
Submenus, or Nested menus ) can have menus within menus 
within menus, up to 5 levels of depth. This article will show you 
how to include Hierarchical and Color Menus in your own 
program. 

The Menu Manager programmers have implemented the new 
features in a exceptionally intelligent way. Of course the new 
Menu Manager is backwardly compatible so that all the old 
programs will run their menus correctly, however the new 
features can be added to a program that will run on either the old 
or new Manager. Color can added without any new Tool Box 
calls (though there are a few new ones for Mac // only programs). 
By adding certain resources, which the new Menu Manager looks 
for and uses, the Menus will be displayed in color. Of course 
these resources are ignored by the old Menu Manager. Thus 
Color Menus will be automatically used when the program is 
running on a Mac //, and will not be used when it runs on the Mac 
Plus or SE. The use of Hierarchical Menus are even more 
universal. Not only do they function on the Mac //, but Hierar- 
chical Menus have been implement into the latest System/Finder 
(ie. they run on the Mac Plus and/or SE). Programs using 
Hierarchical menus сап be written without having to worry about 
what machine the program will run on. 

Documenting Programs 

The new system file does have an impact on documenting 
programs however. The capture menu script used to restore the 
ability to capture pulled down menus with cmd-shift-3 only 
partially works with the new system. The figures in this article 
were captured using it, but only after cleaning them up. The little 
arrow character is not correctly displayed when the menu capture 
resource is installed, and in fact, the menu manager pretty much 
gets clobbered so don't try to use it except on a floppy system 
dedicated to that purpose. Another interesting change is that 
cmd-shift-3, which captures the screen in a paint document, only 
works in black and white 2-bit mode. If you try to capture a color 
display, it beeps! 

[Thisisa good place for the Editor to begin his editorial Apple 
bashing about how none of Apple's programs (paint, draw, write, 
project and terminal) have ever been upgraded for new system 
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features. The ‘ole Do as I say, not as I do syndrome. Since Apple 
has announced upgrades of these products, it will be interesting 
next month to see if they work any differently. In any case, the 
very useful menu capture facility, removed with the 128K 
ROMS, is nearly dead and buried now, and that is a shame, since 
it was very useful for this article, even if it didn't really work 
correctly. For anyone wondering what to write about or develop, 
anew screen capture function that handles both nested menus and 
color would be very nice. -Ed] 


RGB Color 


First a quick review of Macintosh // RGB color is needed. 
Unlike the old Quickdraw color where only 8 colors are avail- 
able, the new Macintosh // Quickdraw allows 16,777,216 colors. 
The new Color Quickdraw does this by using the new record type 
RGBColor to define exactly what color is being used (to draw, 
erase, fill, etc.). The format of RGBColor is: 


TYPE 
RGBColor = RECORD 
red : INTEGER; 
green : INTEGER; 
blue : INTEGER; 
END; 


The three unsigned 16-Bit integer values in the RGBColor 
record defines the intensity values for the 3 additive primary 
colors (Red, Green, Blue). Since values of each primary colors 
are in the range 0 to 65535, hex notation is usually easier to work 
with. For example the values ($FFFF,$0,$0) gives a solid red 
RGB color. White is ($FFFF,SFFFF,$FFFF), Black is 


Display 


Fig. 1 Hierarchal Menus 
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($0,$0,$0), medium Gray is ($7FFF,$7FFF,$7FFF) and Yellow 
is (SFFFF,SFFFF,$0). 

Remember that the display device (monitor, printer, etc.) 
that is being used defines what actual color is displayed. When 
some drawing is done in a specific RGB color, the output device 
tries to match the closest specific color it has to draw with. Most 
devices (like the Apple Video Card/Monitor) can display any of 
the range of 16,777,216 colors, but can only display so many at 
a given time. For example the Apple Video Card/Monitor, can 
either display 16 or 256 colors depending on how much memory 
is on the card. So subtle differences in colors can sometimes be 
lost on monitors, especially if many colors are being displayed at 
the same time. 


Color Menus 


As stated, all parts of the menu bar and menus can be 
displayed in any RGB color. These parts include each Menu 
(Title and Background color) and each Menu Item (Title, Mark, 
Command Key and Background color). The information for 
what color to draw each menu part is not stored in the 
MenuHandle nor the MenuList, but in a new data structure, the 
Menu Color Information Table (or MCIT). The MCIT is created 
by the InitMenucallof the Mac // Menu Manager, and is modified 
by subsequential Menu Manager calls. The MCIT contains 1 or 
more Menu Color Entries. There are different types of entries, 
but they all have the following format: 


TYPE 

MCinfoRec = RECORD 
MenulD : INTEGER; 
Menultem : INTEGER; 
RGB1 : RGBColor; 
RGB2 : RGBColor; 
RGB3 : RGBColor; 
RGB4 : RGBColor; 
Filler: INTEGER; 

END; 


The MCIT will always contain a special “End-of-table” entry 
(MenuID = -99). The MCIT can also include 3 other types of 
entries; the Menu Bar Entry, the Menu Title Entry and the Menu 
Item Entry. In all three entries, filler is a reserved integer used by 


“өне ӘНШІ, 
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Fig. 2 Menus nested three deep! 
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the Menu Manager (should not be used by the program). 

In a Menu Bar Entry, MenuID and Menultem equals 0. It 
contains the 4 RGB Colors that are used to draw the default Menu 
Title color, default Menu Background color (background of the 
pull down menu), default Menu Item color and default Menu Bar 
color (RGB1-RGB4, in that order). There should be at most only 
1 Menu Bar Entry, though there does not have to be one. If there 
is not a Menu Bar Entry, the default colors are Black on White 
(normal monochrome menu). 

In a Menu Title Entry, MenuID is not equal to 0 and Menu- 
Itemisequal toO. The MenuID number will match the ID number 
of the Menu it is describing. RGB1 is the Title Color; RGB2 is 
the Menu Bar Color; RGB3 is the default Menu Item color; 
RGB4 is the default Menu Background color. There should be 
at most only 1 Menu Title Entry per each Menu displayed in the 
MenuList, though there does not have to be one. If there is no 
Menu Title Entry to match a Menu, the Menu uses the colors 
defined in the Menu Bar Entry. 

In a Menu Item Entry, MenuID and Menultem do not equal 
0. The MenuID and Menultem defines a specific Menu Item 
(with the Menu ID of MenuID and the Menu Item number of 
Menultem). RGB1 is the Mark color of that Menu, RGB2 is the 
Name color (ie. text), RGB3 is the Command Key color and 
RGB4 is the Background color. There should be at most only 1 
Мепи Пет Entry per each Menu Item displayed in the MenuList, 
though there does not have to be one. If there is no Menu Item 
Entry for a specific Menu Item, the Menu Title Entry is used. 

Thus the Menu Bar Entry defines the global default colors. 
These default colors can be overridden for a specific menu by a 
Menu Title Entry. The Menu Title Entry defines the default 
colors for a single Menu, unless overridden by the Menu Item 
Entry. The Menu Item Entry defines the colors for a single Menu 
Item. 

There are a few ways to alter the MCIT. The Mac // Menu 
Manager has modified two of the older calls so that they work 
with the MCIT. When InitMenu is called, InitMenu checks for 
aresource of type “тс” and ID number 0. Resource of this type 
contain 1 or more Menu ColorEntries. InitMenu loads theentries 
the resource contains into the MCIT (assuming the resource 
exists). That specific resource (type “mctb” and ID number O) is 
usually in the System file of the Macintosh // and usually contains 
the Menu Bar Entry. For most Mac // System files, this resource 
contains the color information for a Black on White menu. By 
altering this resource in the System file, the colors of the menu 
can be changed for all programs. А modified version of the 
resource can be added to any application so that the colors change 
for that application only (because resources inside an application 
override the resource of the same type and ID number that reside 
in the System file). 

The other older Menu Manager call that works with the MCIT 
is the GetMenu call. When GetMenu load a certain “MENU” 
resource, it also looks for the resource of type “mctb” with the 
same ID number. GetMenu then loads the Entries, contained in 
the resource, into the MCIT. Usually the resource holds the 
Menu Title Entry and Menu Item Entries for that specific Menu. 
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The “тс” resources is a variable size resource with the 
following format: 


TYPE 
MenuCInfo = RECORD 
NumEntries : INTEGER; 
Entry: АВВАҮП1.. NumEntries] OF MCInfoRec; 
END; 
MenuCInfoPtr s 
MenuCInfoHd) = 


^ MenuCInfo; 
* MenuCInfoPtr; 


There are also 6 new Mac // Menu Manager calls that work 
with or alter the MCIT. They can get, set and dispose of the 
MCIT, and can get, set and delete individual entries in the MCIT. 
However this is not the best way to alter the MCIT for most cases. 
By using these older calls, the program can still display Menus in 
color, without having to write Macintosh // specific code. 

The sample program shows how to create resources inside a 
program that display color menus. However, instead of using 
RMaker, ResEdit could be used to make these resources. Color 
could even be added to preexisting programs without having any 
effect on the functionality of that program. The following is the 
ResEdit Template to be used when modifying *mctb" resources. 
To add a template to ResEdit, create a resource of type “TMPL” 
and пате *mctb". The template contains the following informa- 
tion: 


Label Туре Comments 
# of Entries ОСМТ 

+0000 LSTC 

Menu ID DWRD 

Menu ID DWRD 

Red1 HWRD could be DWRD also 
Green1 HWRD 

Blue1 HWRD 

Red2 HWRD 

Green2 HWRD 

Blue2 HWRD 

Red3 HWRD 

Green3 HWRD 

Blue3 HWRD 

Red4 HWRD 

Green4 HWRD 

Blue4 HWRD 

Filler DWRD leave empty 
(IZEL) LSTE 


Hierarchical Menus 


Hierarchical Menus are created the same way as any other 


menus; either by using GetMenu or using NewMenu. You can 
use any of the normal Menu Manager (AddResMenu, SetItem, 
CheckItem, etc.) calls to create or modify the Menu. As such, апу 
SubMenu can have all the variations (different Styles, Keyboard 
Equivalents, Disable, Icons, Marks, Scrolling) available on a 
normal menu. 

A Menu becomes a Hierarchical Menu when it is inserted into 
the Menu List with the InsertMenu call. Normally InsertMenu 
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contains the MenuHandle and a integer value thatexplains where 
in the list to insert that specific Menu. If that value is zero, the 
menu is added to the end of the Menu List. With the new Menu 
Manager, if that value was set to -1, the Menu becomes a 
Hierarchical Menu. It will become part of the MenuList, but it 
will be placed in a “Hierarchical” portion of the list. It will not 
be displayed in the Menu bar. Hierarchical Menu will only be 
displayed when the menu item it attached is highlighted. 

Menu Items become attached to another Hierarchical Menu 
by having 2 values in their data structure. First the Keyboard 
Equivalent byte must be set to $1B. Next the Menu ID of the 
Hierarchical Menu must be placed in the Character Mark byte. 
This can be done directly in the program with the AppendMenu 
and/or SetItemMark calls, or the values can be placed in the 
MENU resources of the program. The example program does it 
this way. Note that the fact that the Character Mark byte must 
hold the Menu ID of the Hierarchical Menu. This limit all 
Hierarchical Menus to the ID numbers 0 to 255. 

When a Menu is selected that contains a Menu Item that is 
attached to a Hierarchical Menu, first the “Father” Menu is 
displayed. If the specific Menu Item is highlighted, the Hierar- 
chical Menu is displayed. If some item in the Hierarchical Menu 
is finally chosen, it’s Menu ID and Item ID are returned in 
MenuSelect (or MenuKey). The fact that the “Father” Menu was 
initially selected is completely invisible to the program. If the 
"Father" Menucontains nothing but SubMenus, it mightnoteven 
be checked for in the Menu Case statement of the program. The 
example program contains such a Menu. 


Final Comments 


The example program demonstrates a simple use of Color 
Menus and Hierarchical Menus. Itcreates a window and displays 
a text message. The user can control the message contents, font, 
size, style, justification and color (Foreground and Background 
colors using the Old Quickdraw color commands). 

The program places the Color, Font, Size, Style and Justifica- 
tion menus into the Display Menu, and places the Foreground and 
Background menus into the Color Menu. Thus, one Hierarchical 
Menu controls all of the standard Text editing menus that are 
appearing in more and more programs. This will provide more 
spaceon the Menu Bar; space that is needed as features are added 
to programs. 

The "mctb" resources color the Menu Titles Green, the Desk 
Accessory's Menu Items Red, the Color Menu Items the various 
colors and the rest of the Menu Items Blue. Besides showing the 
colors the text can be displayed in, the other color menus form the 
Menus Items into logical groups for quick recognition. 

Some last hints about using Color Menus and Hierarchical 
Menus, overuse of these new features will confuse a user, not 
enhance the program. Do not use colors combinations that are 
hard to read (ie. Red on Blue background). Group types of menu 
items into the same color; do not give menu items arbitrary 
colors. Do not go down too many layers of depth with Hierarchi- 
cal Menu, or a user will lose track of where he is. Be restrained! 
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The is one other change to the Menu Manager on the Mac // 
that is worth mentioning. How and where a menu bar is drawn 
is no longer in ROM. Now the ROM calls a Menu Bar Defproc 
to place the Menu Bar. The same way the Menu Defproc handles 
the menu (drawing, highlighting, calculation size), the Menu Bar 
Defproc handle the Menu Bar. Menu Bar Defproc are stored in 
resources as type “mbdf” and the default Menu Bar Defproc has 
ID number 0. There is a new Menu Manager call, named 
InitProcMenu, that allows switching of a Menu Bar Defproc. 
Perhaps a Menu Bar that displays icons or pictures, or a defproc 
that draws the Menu Bar along the bottom or right side of the 
screen will be seen in a future article. 


БЕШЕ Menufun ғы 


MenuFun 
n 


Fig. 3 MenuFun selects color 


( MenuFun by Steve Sheets 6/3/87 ) 
( Simple Demonstration of Mec // Menu Manager.) 
PROGRAM LMC; 
( Various Constents:Menu ID Numbers ) 
CONST 


AppleMenuID = 40; 
FileMenuID = 41; 
EditMenuID = 42; 
DispleyMenuID = 43; 
ColorMenuID = 44; 
FontMenuID = 45; 
SizeMenuID = 46; 
StyleMenuID = 47; 
JustMenuID = 48; 
FColorMenuID = 49; 
BColorMenuID = 50; 


( Var:Menus, Window, Text, Rectangle, Done Flag, } 
( 621008; Font, Size and Justification Settings.) 
AR 
AppleMenu, FileMenu, EditMenu, DisplayMenu, ColorMenu, 
FontMenu, SizeMenu, StyleMenu, JustMenu, FColorMenu, 
BColorMenu : MenuHandle; 
MyWindow : windowptr; 
Done : boolean; 
MyStr : str255; 
MyRect : Rect; 
MyFColor, MyBColor, MyFont, MySize, MyJust : integer; 
MyBold, MyItalic, MyUnderline, MyOutline, MyShadow, 
MyCondense, MyExtend : boolean; 
MyStyle : Style; 


(Redraws the window, by creating an update event.) 
PROCEDURE ReDrew; 
VAR 


tempPort : Grefptr; 
BEGIN 
GetPortCtempPort); 
SetPor t CMyW indow); 
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InvelRect (MyRect); 
SetPortCtempPort); 
END; 


(Given the style settings, checks the various Style Menus and 


createsthe correct Style variable.) 
PROCEDURE CheckStyle; 
BEGIN 
MyStyle := Г]; 
IF MyBold THEN 
BEGIN 


SetItemMark(StyleMenu, 1, CHARCdiamondMark)); 


MyStyle := MyStyle + [Bold]; 
END 
ELSE 
SetI temMark(StyleMenu, 1, CHARCnoMark)); 
IF MyItalic THEN 
BEGIN 
SetItemMerk(StyleMenu, 2, CHARCdiamondMark)); 
«ЖЫ := MyStyle + [Italic]; 
ND 


ELSE . 

SetI temMark(StyleMenu, 2, CHARCnoMark)); 
IF MyUnderLine THEN 

BEGIN 


SetItemMark(StyleMenu, 3, CHARCdiamondMark)); 


MyStyle := MyStyle + [Underline]; 

END 
ELSE 

SetItemMark(StyleMenu, 3, CHARCnoMark)); 
IF MyOutline THEN 

BEGIN 


SetItemMerk(StyleMenu, 4, CHARCdiamondMark)); 


MyStyle := MyStyle + [Outline]; 
END 


LSE 
SetI temMark(StyleMenu, 4, CHARCnoMark)); 
IF е THEN 


GIN 
SetI temMark(StyleMenu, 5, CHARCdiamondMark)); 
MyStyle := MyStyle + [Shadow]; 
END 
ELSE 
Seti temMark(StyleMenu, 5, CHARCnoMark)); 
IF MyCondense THEN 
BEGIN 


SetItemMark(StyleMenu, 6, CHARCdiamondMark)); 


MyStyle := MyStyle + [Condense]; 
END 


ELSE 

SetItemMark(StyleMenu, 6, CHARCnoMark)); 
IF MyExtend THEN 

BEGIN 


SetItemMark(StyleMenu, 7, CHARCdiamondMark)); 


MyStyle := MyStyle + [Extend]; 
END 


ELSE 
SetItemMark(StyleMenu, 7, CHARCnoMark)); 
END; 


( Given the color number (1-8), returns color constant.) 


FUNCTION GetColor (C : integer) : longint; 
BEGIN 
one С OF 
GetColor : := BlackColor; 
2 
GetColor := WhiteColor; 
24 
GetColor := RedColor; 
4 . 


GetColor := GreenColor; 
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GetColor := BlueColor; 
6: 

GetColor := CyanColor; 
7: 

GetColor := MagentaColor; 
8 . 


GetColor := YellowColor; 


( Draws Text in Rectangle in correct Colors, Font, Size, 
Style and Justification.) 
PROCEDURE DoDrew; 
VAR 
tempStr : str255; 
tempInteger : integer; 
BEGIN 
ForeColor(GetColor(MyFColor)); 
BackColor(GetColor(CMyBColor 22; 
GetItemCFontMenu, MyFont, tempStr); 
GetFNunCtempStr, tempInteger); 
TextFontCtempInteger 2; 
CASE MySize OF 


1: 
TextSize(9); 
TextSize( 10); 
TextSize(12); 
TextSize(18); 
TextSize(24); 
TextSize(32); 

END; 
TextFace(MyStyle); 
TextBox(POINTERCord4(@MyStr) + 1), LENGTH(MyStr), 
MyRect, MyJust - 2); 
END; 


( Edit the Text. ) 
PROCEDURE DoEdit; 


AR 
MyDialog : DialogPtr; 


о л a CO N 


N : integer; 
MyH : hendle; 
MyR : rect; 


BEGIN 
MyDialog := GetNewDialog( 130, NIL, POINTERC- 122; 
GetDItenCMyDialog, 4, М, MyH, М); 
SetITextCMyH, MyStr); 
REPEAT 
ModalDialog(NIL, N); 
UNTIL (N = 1) OR (N = 2); 
IF N = 1 THEN 


EGIN 
GetITextCMyH, MyStr); 
ReDraw; 
END; 
DisposDialog(MyDialog); 
END; 


( Standard main menu procedure that handles menu selections. 
Can show About Box, Edit the Text, change the Done Flag (so 
the program quits), handle edit commands 
(Cut,Copy,Paste,Clear), and change all the Colors, Font, Size, 
Style and Justification of the Text. } 

PROCEDURE MainMenu CtempResult : LONGINT); 


VAR 
tempInteger : integer; 
tempStr : str255; 
BEGIN 
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tempInteger := LoWordCtempResult); 
CASE HiWordCtempResult) OF 
AppleMenuID : 
IF tempInteger = 1 THEN 
tempInteger := Alert( 128, NIL) 
ELSE 
BEGIN 
GetItemCeppleMenu, tempInteger, tempStr); 
қ Қ ыды := OpenDeskAccCtempStr); 
М . 


FileMenuID : 
IF tempInteger = 1 THEN 
DoEdit 


ELSE IF tempInteger = 3 THEN 
Done := САЛег{С 129, NIL) = 2); 
EditMenuID : 
IF NOT SystemEditCtempInteger - 1) THEN 
sysbeep( 1); 
FColorMenuID : 
IF CtempInteger <> 0) AND CtenmpInteger © 
MyFColor) THEN 
BE 


GIN 
CheckItenCFColorMenu, MyFColor, false); 
MyFColor := tempInteger; 
CheckItemCFColorMenu, MyFColor, true); 
ReDrew; 
END; 
BColorMenuID : 
IF CtenpInteger € 0) AND CtempInteger € 
MyBColor) THEN 
BEGIN 
CheckItem(BColorMenu, MyBColor, false); 
MyBColor := tempInteger; 
CheckI temCBColorMenu, MyBColor, true); 
ReDrew; 


END; 
FontMenuID : 
IF CtempInteger € 0) AND CtempInteger © MyFont) 


BEGIN 
CheckItemCFontMenu, MyFont, false); 
MyFont := tempInteger; 
CheckItemCFontMenu, MyFont, true); 
ReDrew; 

END; 

SizeMenuID : 
IF CtempInteger 9 0) AND CtempInteger € MySize) 


BEGIN 
CheckItem(SizeMenu, MySize, false); 
MySize := tempInteger; 
CheckItem(SizeMenu, MySize, true); 
ReDrew; 

END; 

StyleMenuID : 
BEGIN 
CASE tempInteger OF 


1: 
MyBold := NOT MyBold; 


THEN 


MyItal ic := NOT MyItalic; 
MyUnderLine := NOT MyUnderL ine; 
MjOutline := NOT My0utl ine; 
MShedor := NOT MyShadow; 


© л » о N 


MyCondense :z NOT MyCondense; 
7 . 


MyExtend := NOT MyExtend; 
OTHERWISE 
END; 
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CheckStyle; InsertMenu(BColorMenu, -10; 


ReDraw; 
END; DrawMenuBar ; 
JustMenuID : MyWindow := GetNewWindow( 128, NIL, POINTER(-1)); 
IF CtempInteger <> 0) AND CtempInteger © MyJust) MyRect := MyWindow^ .portRect; 
THEN GetIndString(MyStr, 128, 1); 
BEGIN InitCursor ; 


CheckItemCJustMenu, MyJust, false); 

MyJust := tempInteger; 

CheckItemCJustMenu, MyJust, true); 

ReDrew; 

END; 
OTHERWISE 
d 

HiliteMenuC2); 
END; 


Setup for Menus, Window, Done flag, Text, Rectangle, 


Colors, Font, Size, Style and Justification of the Text.) 


PROCEDURE DoSetup; 

BEGIN 
AppleMenu := GetMenuCAppleMenuID); 
AddResMenuCAppleMenu, ‘DRVR’); 


FileMenu := GetMenuCFileMenuID); 
EditMenu := GetMenuCEdi tMenuID); 
DisplayMenu := GetMenu(DisplayMenuID); 
ColorMenu := GetMenu(ColorMenulD); 


FontMenu := GetMenuCFontMenulD); 
AddResMenu(FontMenu, ‘FONT’); 
MyFont := 1; 

CheckItemCFontMenu, MyFont, true); 


SizeMenu := GetMenu(SizeMenuID); 
MySize := 3; 
CheckItem(SizeMenu, MySize, true); 


StyleMenu := GetMenu(StyleMenuID); 
MyBold := false; 

MyItalic := false; 

MyUnderLine := false; 

MyOutline := false; 

MyShadow := false; 

MyCondense := false; 

MyExtend := false; 

CheckStyle; 


JustMenu := GetMenuCJustMenuID); 
MyJust := 3; 
CheckItemCJustMenu, MyJust, true); 


FColorMenu := GetMenuCFColorMenuID); 
MyFColor := 1; 
CheckItemCFColorMenu, MyFColor, true); 


BColorMenu := GetMenu(BColorMenuID); 
MyBColor := 2; 
CheckItemC(BColorMenu, MyBColor, true); 


InsertMenuCAppleMenu, 0); 
InsertMenuCFileMenu, 0); 
InsertMenuCEditMenu, 0); 
InsertMenuCDisplaeyMenu, 0); 
InsertMenuCColorMenu, – 1); 
InsertMenuCFontMenu, - 1); 
InsertMenuCSizeMenu, - 1); 
InsertMenuCStyleMenu, - 1); 
InsertMenuCJustMenu, – 1); 
Inser tMenuCFColorMenu, – 1); 
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Done := false; 


END; 


( Standard main program loop that handles 811 events Cie. 
mouse down, key downs & updates) until the Done flag is set. 


PROCEDURE MainLoop; 
VAR 


BEGIN 


tempEvent : EventRecord; 
tempWindow : windowptr; 
tempCode : integer; 
tempPort : Grafptr; 
tempRect : rect; 
tempLong : longint; 


REPEAT 
SystemTask; 


IF 


GetNextEventCeveryEvent, tempEvent) THEN 


BEGIN 


CASE tempEvent what ОҒ 
mouseDown : 


tempCode := FindWindowCtempEvent.where, tempWindow); 
CASE tempCode OF 
inDrag, inContent : 

BEGIN 


IF tempWindow © FrontWindow THEN 
SelectWindowCtempWindow) 
ELSE 
BEGIN 
IF MyWindow = tempWindow THEN 
BEGIN 
SetRect(tempRect, -25000, -25000, 25000, 25000); 
DragWindow(MyWindow, tempEvent.where, tempRect); 
END; 
END; 
END; 
inGrow : 
BEGIN 
IF tempWindow <> FrontWindow THEN 
SelectWindowCtempWindow) 
ELSE 
BEGIN 
IF MyWindow = tempWindow THEN 
BEGIN 
SetRect(tempRect, -25000, -25000, 25000, 25000); 
tempLong := GrowWindow(MyWindow, tempEvent where, 


tempRect); 


SizeWindow(MyWindow, LoWordCtempLong), 


HiWord(tempLong), false); 


MyRect := MyWindow^.portRect; 
ReDraw; 
END; 
END; 
END; 
inMenuBer : 
Ma inMenu(MenuSe lect( tempEvent . where )); 
inSysWindow : 
SystemClickCtempEvent, tempWindow); 
OTHERWISE 
END; ( of tempCode case } 
END; ( of mouseDown ) 
keydown, autoKey : 
IF BitAndCtempEvent modifiers, cmdKey) © 0 THEN 
MainMenuCMenuKeyCCHRCtempEvent .message MOD 256))); 
updateEvt : 
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IF MyWindow = WindowPtrCtempEvent.message) THEN 
N 


BEGI 
GetPortCtempPort); 
SetPortCMyW indow); 
BeginUpdate(MyWindow); 
DoDraw; 
EndUpdateCMyW indow); 
SetPortCtempPort); 
END; 
OTHERWISE 
END; 
END; 
UNTIL Done; 
END; 
( *&*PROGRAM*** ) 
BEGIN 
DoSetup; 
MainLoop; 
END. 


* MenuFun.R 

ж RMaker Source code for resources to be included in 
* the MenuFun application. Includes about info. 

x 


MenuFun Rsrc 


* Main Window, Alerts, & Text Edit Dialog 
Type WIND 
, 128 
MenuF un 
40 106 240 406 
Visible NoGoAway 


58 106 230 406 
128 
4444 


, 129 
50 106 150 406 
129 
444 


Type DLOG 
, 130 


50 56 175 456 
Visible NoGoAway 
3 


Ü 
130 


Type DITL 
128 


7 


4 


button 
140 120 159 180 
OK 


steticText 

20 65 39 235 

MenuFun by Steve Sheets 
staticText 

40 50 59 250 

Sample Mac // Menu Program 


staticText 
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60 30 119 270 


This program uses the Mac // Menu Manager to create Hiererchi- 
cal and Color Menus. 


, 129 
3 


button 
60 180 80 240 
Cancel 


button 
60 60 80 120 
OK 


staticText 
20 37 40 263 
Do you wish to quit this program? 


, 130 
4 


button 
85 110 105 170 
OK 


button 
85 230 105 290 
Cancel 


staticText 
20 20 40 160 
Text to be Diplayed: 


editText 
45 20 65 380 


* Menu Resources 


(- 


* Menu containing various Menu Items that are attached 
* to other SubMenus Cie. Hierarchical Menu). Note 
* inserted hex values using the \ command. Ex: 
*  /MB sets Keyboard Equivalent to $1B and !\2C sets 
з Character Mark to $2C or 44 (Color Menu ID number). 
,43 
Display 
Color /\1B!\2C 
Font/\ 1B! V2D 
Size/\ 1B! \2E 
Style/\ 1B! \2F 
Justif ication/\ 1B! \38 
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* SubMenus attached to Display Menu 
44 
Color 
Foreground/\ 1B! M31 
Beckground/A 1B! X32 


, 45 
Font 


‚41 

Style 
Bold«B/B 
Italic<I/I 
Under ine<U/U 
Out] ine<0/0 
Shadow<S/S 
Condense 
Extended 


, 48 
Justification 

Right/R 

Lef t/L 

Center 


* SubMenus attached to Color SubMenu 


Foreground 
Black 


,90 
Background 
Black 
White 
Red 
Green 
Blue 
Cyan 
Magenta 
Yellow 


* Starting Display Text 
Type STR! 


д 
Welcome to MenuFun 


* Menu Color Resources 

* First comes the number of entries. Each entry contatins 
* the Menu ID number & the Menu Item number, followed by 

* 4 RGB values (three 16-bit integers in Hex) ending with 

* æa single integer filler. 

Type mctb = GNRL 

* For MMenu Ber Entry CID 80), Default Title & Title Back 

* ground Color is Green on White, while Default Item (Command 
* Mark & Name) and Item Background is Blue on White. 


A 
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* Number of entries 

‚1 

1 

.I 

* Menu ID number & the Menu Item number, in this case 0 & 0 
* Menu Ber Entry. 

020 

.H 

* 4 RGB Colors each containing 3 integers CGreen, White, 

* Blue, White) and the final placing holding integer. 
0000 FFFF 0000 FFFF FFFF FFFF 0000 0000 FFFF FFFF FFFF FFFF 
0000 


* For Apple Menu CID #40), З entries. Title & Title Back 
* ground Coloris Green on White, while Default Item (Command, 
* Mark & Name) and Item Background is Red on White. Items 1 
* & 2 set Merk, Command and Name Color to Blue end Background 
* to White. 

‚40 
‚1 
3 
‚1 
40 0 
.H 
0000 FFFF 0000 FFFF FFFF FFFF FFFF 0000 0000 FFFF FFFF FFFF 
0000 
‚1 
40 1 
H 
0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF FFFF 
0000 


I 
40 2 

„H 

0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF FFFF 
0000 


* For Foreground Menu (10 849), 8 entries (1 per Menu Item). 
х Ist end 2nd Items, Mark, Command and Name colors ere 
* black, while Background color is White. 3rd through 8th 
* [tems ёге the same as ist Item, except that the Mark, 
* Command end Name colors are Red, Green, Blue, Cyan, Magenta 
* or Yellow Cin that order). 

‚49 
‚1 
8 
‚1 
49 1 
.H 
0000 0000 0000 0000 0000 0000 0000 0000 0000 FFFF FFFF FFFF 
0000 


4 
49 2 

Н 

0000 0000 0000 0000 0000 0000 0000 0000 0000 FFFF FFFF FFFF 
0000 

d 

49 3 

Н 

FFFF 0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF 
0000 


4 

49 4 

„H 

0000 FFFF 0000 0000 FFFF 0000 0000 FFFF 0000 FFFF FFFF FFFF 
0000 


I 
49 5 
H 

0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF FFFF 
0000 


.I 
49 6 
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„H 

FFFF FFFF 6000 FFFF FFFF 0000 FFFF FFFF FFFF FFFF FFFF 
0000 

1 

49 1 

H 

FFFF 0000 FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF FFFF FFFF 
0000 

I 

49 8 

„H 

FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF FFFF 
0000 


* For Background Menu CID #50), identical to Foreground Menu. 


‚50 

4 

8 

I 

50 1 

.H 

0000 0000 0000 0000 0000 0000 0000 0000 0000 FFFF FFFF FFFF 
0000 

4 

50 2 


‚Н 

0000 0000 0000 0000 0000 0000 0000 0000 0000 FFFF FFFF FFFF 
0000 

.I 

50 3 

H 
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FFFF 0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF 
0000 


J 

50 4 

„H 

0000 FFFF 0000 0000 FFFF 0000 0000 FFFF 0000 FFFF FFFF FFFF 
0000 

J 

50 5 

Т 

0000 0000 FFFF 0000 0000 FFFF 0000 0000 FFFF FFFF FFFF FFFF 
0000 


.I 

50 6 

Н 

0000 FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF FFFF FFFF FFFF 
0000 

.I 

50 7 

Н 

FFFF 0000 FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF FFFF FFFF 


1 

50 8 

H 

FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF 0000 FFFF FFFF FFFF 
0000 
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MacApp Applications 
How to Think in MacApp 


This is very important. You must think in Russian. You cannot 
think in English and transpose. Do you think you can do that, Mr. 
Grant? 

With those immortal words, our hero, Clint Eastwood, alias 
Mr. Grant, steals a Russian thought-controlled steath fighter, out- 
shoots his way from behind the Iron Curtain, and flies to freedom. 
Learning to think in MacApp is a little like that thought-con- 
trolled Jet Fighter. You must think in MacApp. You cannot think 
in Pascal and transpose. Do you think you can do that Mr. Grant? 


Thinking StarTrek In Object Pascal 


If you’ve been at all intrigued by what you’ve been reading 
about MacApp and object-oriented programming, you’re not 
alone. Apple’s been promoting MacApp heavily, and a number 
of developers, myself included, have discovered that object- 
oriented programming is a new and exciting way of doing and 
thinking about applications. But if you’re even the slightest bit 
confused by what you’ve read, don’t feel too bad - again, you’re 
not alone. I had a lot of trouble when I was first starting out (an 
understatement!), and I’ve talked to other developers who've 
also experienced similar difficulties. Much of my confusion 
centered not so much on MacApp itself, but rather on the more 
fundamental language issues introduced by Object Pascal (aka 
MPW Pascal). If you don't have a good, solid understanding of 
what objects are and how to work with them, you won't have a 
hope in a hot place of understanding what MacApp is all about. 

This article, then, is an attempt to focus on a few of these new 
language issues, to hopefully cast them in a new light. I don't 
think my treatment here is really all that different from what's 
been presented in Apple's documentation, in Kurt Schmucker's 
Object-Oriented Programming for Macintosh, or in earlier is- 
sues of MacTutor. In some cases, it's simply a question of 
emphasis, or of looking at a particular concept or programming 
construct in a slightly different way. 

To make this exposition as “real” as possible, I'm going to 
assume that we're writing a hypothetical Star Trek game and use 
that as a vehicle for my discussion (I personally need to see lots 
of concrete code before I can understand new concepts; you 
might be similar). Anyway, my apologies to Gene Roddenberry 
and Trekkies everywhere for any mistakes; I'm not trying too 
hard to be accurate (although I am trying to be objective). 

As you're probably aware, the fundamental new program- 
ming structure introduced by Object Pascal is the object (if you 
knew that, acigar). Objects are simply packages of data, together 
with the specific code that acts on that data. Objects present a 
good way of modeling the behavior of a particular programming 
entity. 
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In a Star Trek game, for example, a good candidate for such 
an entity might be one of the many ships that are manipulated 
during the game. Let's consider, for example, creating an object 
that represents a Klingon warship. Such a Klingon object would 
represent one ship in our game. It would use its data fields to 
maintain information on its current weapons status, its position, 
and so forth. The methods belonging to the Klingon object would 
manipulate this information to enact the specific behavior we 
expect of Klingon vessels. 

Creating this object in our program is going to involve coding 
statements in at least three different places in the program. First, 
in an INTERFACE section of our program we're going to find 
something like the following: 

TYPE 

TKlingonVessel = OBJECT 

fNumTorpedoes : INTEGER; 
( other relevant fields ) 


PROCEDURE TK1ingonVessel .LaunchTorpedoes; 
... ( other relevant methods ) 


END; ( TKlingonVessel object type ) 

Notice, first of all, that this is a TYPE declaration, and that 
somewhere else in our code we can therefore expect to find a 
corresponding VAR declaration for a variable of this type. In 
particular, this is a declaration for an object type. This object- 
type declaration is our first interesting extension of standard 
Pascal syntax. It shares some of the characteristics of aRECORD 
type, except, most notably, that standard Pascal records don’t 
contain procedures as fields. Strange concept number one. Also 
note that the procedure name LaunchTorpedoes is prefixed by 
the object-type name, TKlingonVessel. 

The naming conventions in the above piece of code, by the 
way, are just that - conventions. Object type identifiers start with 
а "T" and data fields start with an “f”. I'll point out later why 
these conventions are useful. 

Somewhere else in our program we'll find an IMPLEMEN- 
TATION section that contains the actual code for the procedure 
(ie, method) TKlingonVessel.LaunchTorpedoes. It might look 
something like the following: 

PROCEDURE TK1ingonVesse! .LaunchTorpedoes; 


BEGI 
IF fNunTorpedoes > Ø THEN 
BEGIN 


fNumTorpedoes := fNumTorpedoes - 1; 
DoLaunch; 


END; 

The first interesting question I'd like to address is this: given 
this declaration of an object type and the IMPLEMENTATION 
of the single procedure it contains (or at least the single one I've 
shown), how do we invoke, or execute, the code for the procedure 
TKlingonVessel.LaunchTorpedoes? 

If we were working in standard Pascal, the question would be 
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50 trivial as to be meaningless: you simply invoke the procedure 
by naming itat some point in your program. In Object Pascal, it's 
notquite that simple. In ObjectPascal, youcan'texecute the code 
for this method until the object containing it has been created. 
And we haven't created the object yet; we've simply declared an 
object TYPE, a template for the object to be. 

This is one of the fundamental differences between standard 
Pascal and Object Pascal: in standard Pascal, code is fixed and 
immutable - it simply is. In Object Pascal, code has to be created 
on the fly atruntime before уой сап use it. Now, that's a dramatic, 
though slightly inaccurate statement. It's close enough to the 
way things work, however, to be useful. 

How do we create the actual TKlingonVessel object and 
execute itscode? The third piece of our program looks something 
like this: 

VAR 


eKlingonVessel : TKlingonVessel; 
EGIN 


NEWC aKlingonVessel 2; 
eKlingonVessel.fNumTorpedoes := 10; 
eKlingonVessel .LaunchTorpedoes; 


END; 

Obviously this piece of code is a wee bit strange - it's unlikely 
that we'd create a new Klingon object and then immediately ask 
it to blindly launch a torpedo. I plead pedagogical considera- 
tions. Atany rate, here's the VAR statement for the variable I 
mentioned. This code fragment says that we're going to create 
a new object, and that object will be of type TKlingonVessel as 
declared earlier. An object of this type will contain the data fields 
and methods that were declared for that object type. The NEW 
statement then actually creates the object at runtime and makes 
its fields and methods available for use. 

This use of NEW is an extension of the standard Pascal NEW 
procedure. The compiler recognizes that we're creating an object 
and not a standard data structure by the type of the variable that 
we're NEWing, in this case aKlingonVessel. 

Once we've created our object, its data fields become acces- 
sible. The statement 

eKlingonVessel.fNumTorpedoes := 10; 
initializes the field fNumTorpedoes; prior to this statement, the 
value of the field was undefined. Note again the RECORD-like 
syntax used here. Only this time, we're working with a variable 
and not an object type: note that the prefix, or qualifier, is 
changed accordingly. 

Finally, we can execute the code of our launch procedure with 
the statement: 

eK1ingonVessel .LaunchTorpedoes; 

This creation of a new object is known as instantiation, a 
wonderful term; we have created an instance of this object type. 
Its data fields are now stuffable; its code is now executable. 

Toconfuse matters justa bit (just when you thought you were 
getting things under control): the variable aKlingonVessel is not 
the object itself. Close, but no cigar. The variable aKlingon- 
Vessel is an object reference variable, or simply an object 
reference. Why? 

The relationship between an object reference variable and an 
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object is very similar to that between a handle and the handled 
block it points to. An object actually is a handled block, but with 
a few important differences from our standard understanding of 
the term. It floats on the heap, just like a normal handled block, 
and is just large enough to contain space for its data fields and 
code (well, almost). The handle itself, or more properly the 
object reference variable, is exactly four bytes long, as you'd 
expect for a handle. 

OK, I was bending the truth - our object doesn't actually 
contain the code for its methods, as I’ ve stated. Rather, it contains 
apointer that points to where the code actually resides in memory 
(and who knows, or cares where that is?). That's why I said 
earlier that my statement about creating code on the fly at runtime 
is somewhat inaccurate - the code is already there; we just create 
the object that contains the pointer to it. Ken Doyle gave a good 
description of the method-table mechanism that handles this in 
the December '86 issue of MacTutor (saving me from having to 
explain an implementation issue that I don't fully understand 
anyway). 

Syntactically, while an object-reference variable such as 
aKlingonVessel acts much like a handle, notice that we don't 
have to use Pascal's caret symbol to dereference it in order to get 
at the fields of the object it points to. The period separator is 
sufficient. 

There's one other interesting thing to look at. When we make 
the statement: 

eK1ingonVessel .LeunchTorpedoes, 

we might say that we're invoking this method from outside 
the object. But once that method begins to execute, we are, in a 
sense, inside the object. I'm talking here about the subsequent 
code that gets executed by the above line: 


IF fNumTorpedoes > 0 THEN BEGIN 
fNumTorpedoes := fNumTorpedoes - 1; 
DoLaunch; 


Notice, since we’re now on the inside looking out, that we 
needn't qualify the fieldname fNumTorpedoes with the name of 
the object, aKlingonVessel, or the typename, TKlingonVessel. 
Either, in fact, would be an error. And here's one place where 
naming conventions are useful: the "f" in “fNumTorpedoes” 
immediately tells us that this is a field belonging to our object, 
and not something else such as a global variable (in which case 
it would probably start with a “р,” again by convention). What's 
important is that any of the data fields belonging to this object are 
accessible from within any of its methods, as long as the object 
exists. This is an extension of Standard Pascal's scoping rules 
and has important consequences which we'll look at later. 

The matter of DoLaunch is slightly more involved. Since 
we're inside a Klingon vessel object, DoLaunch might be the 
name of another method belonging to type KlingonVessel (that 
I haven't shown), or it might be the name of a standard Pascal 
procedure that's not a method at all. Again, once we're inside an 
object and executing one of its methods, any other methods that 
we invoke that belong to that object are not qualified. Finally, 
there's a minor variation on the first possibility that we'll cover 
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when we look at the subject of inheritance. 

OK, we've now got Klingon vessel objects. More precisely, 
we've got one Klingon vessel object. This represents one ship. 
In a real Star Trek game, we would probably expect to find 
numerous Klingons, and there's nothing to stop us from creating 
other objects of the same TKlingonVessel type. For example: 

VAR 

aKlingon! : 
eKlingon2 : 

BEGIN 

NEWC aKlingon! 2; 
aKlingon1.fNumTorpedoes := 10; 
ӘКІ ingon 1.LaunchTorpedoes; 
NEWC aKlingon2 ); 
eKlingon2.fNumTorpedoes := 30; 
eK1ingon2 .LeunchTorpedoes; 


TKlingonVessel; 
TKlingonVessel; 


Now we've got two Klingon vessel objects floating in quad- 
rant four, as well as in the heap. They share the same code (there 
are two pointers to the single method, Launch Torpedoes), but it’s 
important to note that they each exist independently of the other 
one. In particular, their data fields are unique. This shouldn't be 
abig surprise if you think about creating two RECORD variables 
in Pascal that are both based on the same type definition. 

At the end of the above sequence of statements, aKlingon1 
has 9 torpedoes left, and aKlingon2 has 29 torpedoes remaining. 

OK, we've now got Klingon objects galore, one for every 
Klingon vessel in our game. Let's back up a bit and put the above 
piece of code in context. The question is: where are these 
Klingons being created? In other words, who is creating them? 
Somebody has that responsibility. 

In atypical game, we’ll probably have another object whose 
job it is to mind the board and keep track of turns and other things 
like that. We might call this the game object and declare it to be 
of type TGame. Our TGame object will also be responsible for 
creating all the vessels that are going to appear during the course 
of the game. This sequence of events (non-Macintosh usage 
here) is highly typical of the way most object-oriented programs 
behave at runtime: we initially instantiate one object; it in turn 
instantiates another; and so on down the line. (If you’re astute, 
you might well ask at this point what happens if we just keep on 
instantiating objects, knowing that every instantiation creates a 
new block in the heap. A very good question. Don’t ask; I'll 
come back to this later). 

In any event, if we go back and expand the above piece of code 
just a bit, it'll look something like this: 

( IMPLEMENTATION ) 


TGene . NewVessel; 
VAR 
aKlingon! : 
eKlingon2 : 
BEGIN 
NEWC eKlingonl ); 
eKlingonl.fNumTorpedoes := 10; 
aK 1 ingon 1.LaunchTorpedoes; 
NEWC eKlingon2 ); 
eKlingon2.fNumTorpedoes := 30; 
eK1ingon2 .LaeunchTorpedoes; 
... (other stuff ) 
END; ( TGame.NewVessel ) 


TKlingonVessel; 
TKlingonVessel; 
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AILT'vereally done is bracket the code we saw earlier between 
the name of the game method and an END statement. Again, 
we're being somewhat unrealistic for the sake of pedagogy. It's 
much more likely that this New Vessel method of our game object 
would be used to create one Klingon, and not two, at a time, and 
that we'd invoke it whenever we wanted to create a new one (as 
indicated by a menu or dialog selection, or whatever). Since 
these objects differ only in the number of torpedoes we initialize 
them with (at least according to the limited context I'm showing 
here), we'd probably pass ina parameter like NumTorpedoes that 
immediately gets stuffed into the fNumTorpedoes field. In other 
words: 


TGame .NewVesselC NumTorpedoes : INTEGER ); 
VAR 

eKlingon TK] ingonVessel ; 
BEGI 


NEWC aKlingon ); 
eKlingon.fNumTorpedoes := NumTorpedoes; 
eKlingon.LeunchTorpedoes; 
... (other stuff ) 

END; ( TGame.NewVessel ) 


To be able to keep track of individual Klingons, the TKlin- 
gonVessel type would also probably have a field called fID, and 
we'd increment this field by one for each new ship we added so 
that each Klingon had a unique number. 

Rather than initializing our objects exactly as I've shown 
above, however, it’s a much more common practise to provide 
each object with its own initialization method, and pass our 
parameters to the method to let the object initialize its own fields. 
This occurs throughout MacApp. To wit: 


NEWC eKlingon 2; 
eKlingon.IKlingonVesselC NumTorpedoes ); 
eKlingon.LeunchTorpedoes; 


and 
TKlingonVessel.IKlingonVesselC NumTorpedoes: INTEGER); 


fNumTorpedoes := NumTorpedoes; 
... ( other initialization stuff ) 


What can we say about the name of the method, IKlingon- 
Vessel? Again, simply a matter of convention, in which an “I” 
(obviously standing for "Init") is prefixed to the object name. 
OK, that’s a long digression. The main reason I’ve shown the 
above code is to pose one further query (I love doing that; can't 
you tell?). 

The question is this: once the delimiting END statement is 
reached in the NewVessel method, what happens to the objects 
that were created there? Well, ina word: nothing. They continue 
to exist in the heap, but there's no longer any way to reference 
their fields or methods from outside them. The only way we had 
of doing so within the New Vessel block was to use our reference 
variable, aKlingonVessel (or aKlingonl or aKlingon2, as appro- 
priate). Pascal's scoping rules say that these variables are local 
to the method and cease to be once the block is exited. This is a 
problem, since our game object is likely to want to communicate 
with them later on. 
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The answer is to realize again that an object-reference vari- 
able is just that: a variable. And the value of a variable is a 
perfectly good candidate for sticking into one of the data fields 
of our game object via a Pascal assignment statement. That way, 
since the fields of the object continue to existas long as the object 
itself exists, we'll be able to get at any “subordinate” objects that 
are referenced there at any time we like. First, we'll have to add 


the necessary reference field to our TGame TYPE declaration: 
TYPE 
TGame = OBJECT 
fTheKlingon : TKlingon; 
... — (other relevant fields ) 
PROCEDURE TGame.NewVesse] ; 
... (other relevant methods ) 
END; ( TGame object type ) 


We can then do the following simple assignment in our 
TGame.New Vessel method: 


TGane . NewVessel ; 
VAR 


eKlingonVessel : TKlingonVessel; 
GIN 


NEWC aKlingonVessel ); 

fTheKlingon := eKlingonVessel; ( <<- } 
eKlingonVessel.fNumTorpedoes := 10; 

( or fTheKlingon.fNumTorpedoes := 10 ) 


( ... etc. ) 
That's it! We've now established a communcation link, if 
you will, between our game object and this particular Klingon 
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vessel. No matter what other method of the game object may be 
executing later on, the game will be able request this Klingon to 
launch torpedoes or perform any of its other methods by using the 
fTheKlingon reference field. The syntax for doing so, by the 
way, is almost identical to what we've already seen. For 
example, if Klingons have a method that allows them to fire a 
phaser bank (I don't even know if Klingons have phaser banks!), 
the game object can request one to do so simply by saying 

f TheK 1 ingon.F irePhesers; 

We can even extend this usage into stranger realms. If our 
Klingon type has a method that allows it to scan neighboring 
quadrants for enemy warships and report their location, the game 
object can ask it to do so by saying 

EnemyPosit := fTheKlingon.ReportEnemyPosit; 

This is an example of a method that’s actually a function, 
rather than a procedure. This construct might seem somewhat 
strange if you haven’t encountered it before. I remember when 
I was reading the documentation and seeing constructs like this 
for the first time; there was a lot of head scratching. Hopefully, 
you’re not as slow as I was. 

I’m going to leave it at that for the moment. There is a lot 
more. And we haven’teven talked about inheritance, overriding, 
SELF, or a number of other object-oriented subjects. Stay tuned 
next issue for Romulans, Vulcans, and the other denizens of deep 
space. Get objective. 2 


Howard Katz is an expert іп МасАрр & 4th Dimension 
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Macintosh IT 
Life, Quickdraw & The Picker 


Color Life 


Life is one of the oldest computer “Games”. Besides being an 
extremely interesting mathematical puzzle, even a black and 
white Life program can provide hypnotising graphic animation. 
Itis almost appropriate that this column’s first Color Quickdraw 
example is this classic program. Using the full color of the 
Macintosh //, Life is more spell binding than ever! [Yeah, now if 
Apple would ever ship us some color monitors maybe we’ ll see 
what this program can really do some day! -Ed] 

This article will detail the development of a Color Quickdraw 
program, Color Life. It will explain how to check for Color 
Quickdraw, how create Color Grafports/Windows, how the 
Color RGB Model works, how Color Drawing works, how to use 
the Color Picker Package and how tocreate Pop Up Menus. First 
however it will explain what the game of Life is about... 


Game of Life 


Life simulates the life and death of a group of cells from one 
generation to the next. Usually the goal is to find some stable life 
form (ie. one that will not die). Life was originally designed by 
Prof. John Conway at the University of Cambridge. It first 
appeared in Martin Gardner's "Mathematical Games" column of 
Scientific American in October 1970. Scientific American and 
Byte Magazine are two of the main sources of good articles on 
Life. 
BESGESUGNCCEAEUE MCA M KINH NEUE a M CMT 


Steve wins our Program of the Month 
award for his excellent treatment of the 
whole subject of color quickdraw as pre- 
sented in this example program. Enjoy an 
extra $50 on MacTutor, and thanks for 
sharing the technology! 


The rules of Life are simple. The game is played on a two 
dimensional grid of a certain size. Each spot (or cell) on the grid 
can be alive or dead (empty). Also each cell is surrounded by it's 
8 neighboring cells, which can also be alive or dead. The number 
of living cells around the center cell becomes very important in 
calculating deaths and births each turn. 

Every turn (usually called a generation), a living cell can die 
or live on to the next generation. Also a empty cell can have a 
birth (1e. cell becomes alive). If alive cell is surrounded by 2 or 
3 cells this generation, it will survive till the next generation. If 
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Regions 


Fig. 1 Color Quickdraw (cmd-shift-3 only works 

In black and white!) 
a live cell is surrounded by 1 or less cells this generation, it dies 
(from starvation). If the cell is surrounded by 4 or more cells this 
generation, it dies (from over crowding). Finally if a empty cell 
is surrounded by exactly 3 living neighbors, there is a birth there. 
Next generation a new cell exists at that spot. 

From these simple rules, Life emerges. 


Color QuickDraw 


The very first thing a Macintosh // Color program has to 
check for is what environment the program is running in. The 
program is not actually looking for a Macintosh //; it requires 
Color Quickdraw to run. While the Macintosh // is now the only 
computer with Color Quickdraw, it may not be in the future 
(upgraded Mac //, Mac SE with Color Quickdraw expansion card 
or even a Mac ///). 

No matter what the computer, if Color Quickdraw exists on 
the machine, the two high bits of the low-memory global ROM85 
(word at $028E) will be cleared (set to zero). By examining this 
memory location, a program can discover if Color Quickdraw 
exists. The check for Color Quickdraw should be done after the 
normal Mac Initialization (InitGraf, InitFont, InitWindow, etc.), 
but before any Color Quickdraw commands are called (creating 
Color Grafports or color Pixel Patterns). If Color Quickdraw 
does not exist, the program should politely inform the user that 
he needs a Macintosh //. А system bomb is not a polite way of 
informing the user! | 


Color Grafports & Color Windows 


Once the program knows Color Quickdraw exists, it can 
create and work with Color Grafports. All the new Color 
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Quickdraw commands must be done on a Color Grafport, not an 
old-style Grafport. All the older Quickdraw commands have 
been expanded so they can work with either a Grafport or a Color 
Grafport (also called cGrafport). The cGrafport data structure is 
the same size as the older Grafport structure. While many data 
fields are the same, some have been changed. The exact format 
is not important for this program since none of the fields are 
accessed directly. The new cGrafports are allocated in manners 
similar to the old Grafports (either a NewPtr call or a pointer to 
a holding Variable). However, instead of using the Quickdraw 
commands OpenPort, InitPort and ClosePort, the new Color 
Quickdraw commands OpenCPort, InitCPort and CloseCPort 
are used to open, init and close a Color Grafport. 

In practise, the new Color Quickdraw Port commands are 
used as often as the older Quickdraw Port commands; that is 
almost never. The vast majority of the Macintosh programs draw 
on a Window (which keeps track of the Grafport itself). Gener- 
ally the only time a Macintosh program directly manipulates a 
Grafport is when using an off screen bitmap. 

The Window Manager has been expanded to include Color 
Windows. The changes in the Window Manager are similar to 
the changes in Color Quickdraw. There is a new Color Window 
Record of the same size as the old Window Record. All of the 
field are the same except the Port field now contains a cGrafPort 
instead of a Grafport. All existing Window Manager calls have 
been expanded to so that either a Window Pointer or a Color 
Window Pointer can be used with them. Where the NewWindow 
or GetNewWindow command was used to create a window, the 
NewCWindow and GetNewCWindow commands create a color 
window. The two new commands even have the same parame- 
ters and purpose (create a window from scratch or from a window 
resource) as the old commands. They just return a Color Window 
instead (complete with a correctly created Color Grafport). 


RGB Color 


To understand exactly how Color Drawing is handled on the 
newly created Color Grafport/Windows, the RGB color model 
must be reviewed. Color Quickdraw uses a RGB color model as 
an conceptional model for all drawing. A color is defined as 3 
non-signed integer values (0-65535). This defines the strength of 
the Red, Green and Blue portions of the color. A Black color 
would have the values 0,0,0, while white would have 65535, 
65535, 65535. Blue would be 0, 65535, 0, while Purple would 
be 65535, 0, 65535. There are 1,777,216 distinct colors in this 
model. When something is conceptionally drawn, it must be in 
a color defined by this model. 

Inreality, the number of colors that can be drawn at one time, 
is dependenton the pixel depth of thecolor device. Most graphics 
devices are video card, but they can be almost anything (printer, 
off screen bit map, etc.). A color device that can allocate 4 bits 
of memory for each pixel (pixel depth of 4), can use 16 colors at 
one time (2 to the 4th power). A color device that has pixel depth 
of 8, can have 256 colors at one time (2 to the 8th power). 
Remember that usually the user can set what pixel depth the video 
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Ten Steps %Т 
Loop til Button 236L 


Quickdraw 


Fig. 2 Our menus for the game of life 


card is using by using the Monitor portion of the Control Panel. 
A 8 pixel depth card may be only using 4, 2 or even 1 pixels at a 
specific moment. When color Quickdraw tries to draw in a 
specific RGB color, it uses the Color Manager to find the closest 
match on the graphics device. That is the color that is actually 
displayed. 

A good example of this would be trying to display a light, 
medium and dark shade of red. A video card which has been set 
(and as enough memory) for a pixel depth of 8 would probably 
have a few shades of red. Even if the shades were not the exact 
RGB colors requested, the user would at least know that one 
shade was darker and one shade lighter than regular red when the 
colors were displayed on the screen. Suppose then the user set the 
video card pixellevelto4, thus only having 16colors at one time. 
There most likely would only be one red color being used by the 
video card at one time. Chances are that the programs 3 red RGB 
shades would match to the cards single red color (it would be the 
closest match for any of them). The user would then not be able 
to tell the 3 colors apart on the screen. 


Fig. 3 The Life Game in Living(?) Color 
(Pictured is the seventh generation; the other 
generations are in color and cannot be captured) 
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The Color Quickdraw commands RGBForeColor and 
RGBBackColor set the RGB value of the Foreground and Back- 
ground color. Remember that when called, these routine use the 
Color Manager to determine the best RGB color match of the 
graphics device thatis being drawn on. This is the true RGB color 
that will be displayed on the screen. 

АП text is drawn in the Foreground Color. Copybits will 
display bitmaps in the Foreground and Background Colors . Set 
pixels will appear in the Foreground Color; unset pixels will 
appear in the Background Color. The Foreground and Back- 
ground Colors may also effect the drawing of a new Color 
Quickdraw data structure, the Pix Pattern. 


Color Pix Patterns 


Select Color: 


Most commonly used Quickdraw 
drawing commands are done with the Pen. 
The Move and Moveto commands use the 
current setting of the pen. The various 
Paint commands (PaintRect, PaintOval, 
PaintPoly, etc.) also use the pen's settings. 
Old Quickdraw would draw the pen using 
the Pen Pattern; Color Quickdraw draws 
using the Pen's Color Pattern or Pix Pat- 
tern. Inold Quickdraw, similarto the Pen 
Pattern, there is Background Pattern. All 
Erase commands (EraseRect, EraseOval, 
ErasePoly, etc.) used the Background 
Pattern to draw with. With Color Quick- 
draw, similar to the Pen’s Pix Pattern, 
there is a Background Pix Pattern. What 
these two Pix Pattern displays depend on 


how the Pattern was created and thus what 
type of Pix Pattern it is. 


There are 3 types of Pix Patterns. A Pix Pattern variable is a 
handled to a very elaborate data structure (including handles to 
other more complex data structures). For this discussion the 
actual values and formats of the data type is not important. 

The simplest Pix Pattern is a monochrome Pix Pattern. 
Basically the old Quickdraw’ 8 by 8 Pattern is expanded to a Pix 
Pattern with no preset colors. Instead the monochrome Pix 
Pattern always uses the current RGB Foreground and Back- 
ground color to draw in. Where bits (pixels) in the pattern are set, 
the pixel is drawn in the Foreground color, where they are 
Cleared, it is drawn in the Background color. Changing the 
Foreground or Background color, does not change the Pix 
Pattern. Any future drawing with the Pix Pattern will be in the 
new colors. 

The Foreground and Background Pix Patterns can be reset by 
using the old PenPat and BackPat command. On a Color 
Quickdraw Grafport/Window, these commands reset the Fore- 
ground and Background Pix Pattern to a newly created mono- 
chrome Pix Pattern (using the Pattern that is passed as the 
model). Thus by setting RGB Foreground Color to red, the RGB 
Background color to white and the PenPat to a brick pattern, the 
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various Pen Drawing commands would draw with a red and 
white brick pattern. If RGB Foreground Color was suddenly set 
to Blue, the Pen Drawing commands would draw with a blue and 
white brick pattern. Thus the PenPat and BackPat commands are 
two methods to set the Pen Pix Pattern and the Background Pix 
Pattern. 

The second type of Pix Pattern is the RGB Pix Pattern. This 
Pix Pattern contains ап approximation of acertain RGB color. To 
make it, first a empty Pix Pattern must be created using the 
NewPixPat function. This Pix Pattern has no value at this point. 
Then the Pix Pattern and a specific RGB value is passed to 
MakeRGBPat. This reconstructs the Pix Pattern (it is a handle, 


Hue 


Saturation 
Brightness 
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Green |65555 | 
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Fig. 4 The Color Picker Dialog in black and white 


remember) into a RGB Pix Pattern. If there is an RGB color used 
by the Graphics device that is close enough to the RGB color, that 
entire Pix Pattern is set to that color. If there is notan RGB color 
that close, Quickdraw tries to construct a Pix Pattern of that 
approximates that RGB pattern. It does this by mixing 2 RGB 
colors the graphic device allows in the Pix Pattern. This process 
is called dithering. In the above shades of Red example, imagine 
if the three red shades were used to create three Pix Patterns. On 
a 8 Pixel video card, the three Pix Patterns would probably 
display a solid red pattern, each red a different shade. When the 
video card was set to 4 Pixel mode, the medium shade would 
probably still remain a solid red pattern. However the lighter red 
Pix Pattern would display a pattern mixing red and white, while 
the darker red Pix Pattern would display a pattern mixing red and 
black. When running the example program, play with the Pixel 
depth of the video Card (using the Monitor portion of the Control 
Panel) to getan idea of how these Pix Patterns appear. Notice that 
every time the Pixel depth changes, the RGB Pix Pattern seems 
to be recalculated without ever calling the MakeRGBPat routine. 

The last type of Pix Pattern is the Full Color Pix Pattern. This 
is the most powerful Pix Pattern. It can have almost any size and 
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any color or combination of colors. This Pix Pattern can be 
created using the NewPixPat, and then having the data structure 
stuffed with the correct values. The other, easier method of 
creating this Pix Pattern is to read it in from a resource file using 
the GetPixPat function. The Pix Pattern read in can be of any 
type, but usually GetPixPat is used only for Full Color ones. This 
type of Pix Pattern (and example of the resource data structure) 
is not used in the example program. 

Once the Pix Patterns are created, the new Color Quickdraw 
commands PenPixPat and BackPixPat can be used to set the Pen 
Pix Pattern and Background Pix Pattern. Remember Pix Patterns 
are handles. Calling the PenPixPat and BackPixPat command (or 
the PenPat and BackPat command) does not dispose of the old 
Pix Pattern if it was set using PenPixPat and BackPixPat. The call 
only resets the handle in use; the original data remains un- 
changed. Pix Pattern handles created by the program (using 
NewPixPattern or GetPixPattern) are safe and can be reused. 
This is not true of Pix Patterns created using PenPat or BackPat. 
Somehow Color Quickdraw keeps track of Pix Patterns created 
this way, and disposes of them when they are not needed (the 
program does not have to do this). 


Other Color Commands 


Besides using the older Quickdraw commands, Color Quick- 
draw has also been expanded to include six new color operations; 
FillCRect, FillCOval, FillCRoundRect, FillCArc, FillCRgn, 
FillCPoly. They are similar to the old Quickdraw Fill commands 
(FillRect, FillOval, FillRoundRect, FillArc, FillRgn, FillPoly). 
However instead of being passed a specific Pattern to fill the 
graphics area, they are passed a specific color Pix Pattern (of any 
of the 3 defined types). The graphic area is then filled with the 
specific color Pattern. These commands completely by pass the 
existing Foreground RGB Color, Background RGB Color, 
Foreground Pix Pattern and Background Pix Pattern. 


Color Picker Package 


While the program has select a specific RGB color, a user may 
wish to pick a new color (ex. a paint program). Having the user 
pick the exact color he wants and provide a good interface to do 
this, is not a trivial task. Fortunately (and after a lot of good 
forethought by who ever developed Color Quickdraw) there 
exists a standardized way of letting the user to this; the Color 
Picker Package. The Color Picker Package, like all Packages, is 
not a set of Rom resident routines. The Package is stored as a 
system resource, to be read in when the program needs it. But like 
the Standard File Package (with it's SFGetFile and SFPutFile 
dialogs), the Color Picker can be used easily by any program. The 
Picker will be the standard way of selecting RGB colors and 
should be quickly learned by all Macintosh users, just as 
SFGetFile and SFPutFile were. Also like SFGetFile and SFPut- 
File, if there are any upgrades to the Color Picker Package, a 
program using the Picker will automatically use the new version 
without having to be modified. 
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The main call in the Color Picker Package is the GetColor 
function. The routine is passed a point at which the dialog is 
drawn (the dialog is centered if the point is set to 0,0), a prompt 
string, an in going RGB color and a VAR to an out going RGB 
color. The routine will display and run the Picker dialog. The 
function will return False if the user presses Cancel. If he presses 
OK, the function will return True and the out going RGB variable 
will contain the new RGB color. If that RGB color is being used 
for something, remember to update everything (RGB variables, 
PixMaps, Color Windows, etc.). 


PopUp Menus 


One of the new user interfaces on the Macintosh is the Popup 
Menu. This menu is similar to the normal Menu Bar based menu, 
but can appear anywhere on a window. This feature is not 
exclusive to the Macintosh //. The latest System/Finder has been 
patched so that any Macintosh with the Enhanced Roms or later 
(Mac 512KE, MacPlus, Mac SE, Mac //) have the feature. While 
the PopUp Menu call (PopupMenuSelect) is not documented in 
the current release of Inside Macintosh V from APDA, the Rom 
call is implemented in the current release of MPW from APDA. 

The Menu to be used as a Popup menu must be created the 
same way any other Menu is created (with the NewMenu or 
GetMenu commands). The Menu must then be added to the 
Menu List with the InserrMenu command. However unlike 
normal menus, the beforeID parameter of the InsertMenu call 
must beset to -1. This places the Menu in the Menu List, but does 
not displays it. When a mouse down occurs at the correct spot in 
a window, ће PopupMenuSelect Function is used. This function 
is passed the Popup Menu to be displayed, the vertical and 
horizontal position of where the popup menu should appear (in 
global coordinates) and the numberof the menu item that initially 
should appear under the cursor. Depending on the position, this 
menu can be scrolling. The function return a long integer value, 
exactly like the MenuSelect or MenuKey function, that contains 
the Menu ID number and Item number in the High and Low 
words. After the call is made (and the menu disappears), the 
Menu should be removed from the menu list. 


The Code 


After explaining the new calls, the actual program is fairly 
simple. It displays a Life game in color. Depending on how old 
thecellis (0 generations or dead, 1 generation, 2 generation, etc.), 
adifferent RGB color is used to display it. Cells 7 generations or 
older use the same color (usually they have stabilized). TheRGB 
values are converted into RGB Pix Patterns. Try different color 
combos. Having a black background and lighter cells create a 
striking image. Play with the number of Pixels the video card is 
using and see the effect. 

Click in the Life window to create or erase the Life cells. Use 
the Action Menu to cycle through various numbers of genera- 
tions. Use the Show Menu (and About Life Menu) to display the 
other windows. Click in the Color Window to use a Popup Menu 
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to select a color to change and then use the Color Picker to create 
а new color. Finally use the Save and Load Menus to create and 
use Life Documents. Notice that the Save and Load commands 
saves the RGB colors also. The program has a long, but 
instructive drawing routines (specifically for the Quickdraw 
Window) that provide examples of how the old and new Drawing 
Operations (Rect, Oval, Arc, Polygon, etc.) work. It also includes 
a number of useful procedures including how to identify if color 
quickdraw is running. A PopUpMenu routine illustrates getting 
colors with the color picker as well. This should provide a wealth 
of useful information since Inside Mac volume 5 is pretty much 
useless due to it's inaccurate information. 


The program was written in Lightspeed Pascal, and MPW 2.0 
and used the new Build feature of MPW to automatically compile 
itself. Of course the program can be compiled/linked by hand. 
The source includes the Pascal file, Resource file and Make file 
for the MPW version, and the main, globals unit and color stuff 
unit for the LS Pascal version. The LSP version is shown here and 
is virtually identical to the MPW version, except that it is broken 
into units to keep the main segment under 32K, and the resources 
are given in RMaker format. If you are typing it into MPW, note 
the include file names required in the comment at the top of the 
program. It should be easily ported to either Turbo Pascal or TML 
Pascal as well. Both the MPW and LSP versions are included on 
the source code disk for this issue if you don't want to type it in. 
Be sure to use а version of your compiler which supports the new 
Inside Macintosh Volume 5 traps and equates. ForLS Pascal, this 
is version 1.1, which was released last month at the Boston Expo. 

The Life algorithm used here is a brute force method, there are 
plenty of more elegant (translate faster) ones around. This 
program was designed to be readable first, speedy second. If it 
was not for the faster speed of the Mac //, this program would 
almost be to slow. 

Next Issue... Palatte Manipulation and Animation! 


PROGRAM ColorLife; 
( А small Mac // Color Application written by Steve Sheets. 
It plays the original Life game. It also demonstrates some of 
the new commands of Color Quickdraw. LS Pascal version.) 
(Memtypes, Quickdraw, OSIntf, ToolIntf, PackIntf, PickerIntf;) 

USES 

ROM85, ColorQuickDraw, ColorMenuMgr, ColorWindowMgr, 

PickerIntf, myColorGlobals, ColorStuff; 


(Called if Color Quickdraw does not exists to explain why the 
program can not be run.) 


PROCEDURE DoSorry; 
VAR 


n : integer; 
BEGIN 
n :* Alert(sorryID, NIL); 
END; 


(Standard Init calls to set Macintosh up (regardless if it is 
а Mac // or not.) 
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PROCEDURE DoInit; 

BEGIN 
InitGrafC@thePort); 
InitFonts; 
FlushEventsCeveryEvent, 9); 
Ini tWindows; 
InitMenus; 
TEInit; 
InitDialogsCNIL); 
InitCursor; 

END; 


(Does the setup for this program Conly if there is Color 
Quickdraw). Makes the Menus, clears the Dishes, Sets the 
Colors, make the Color Patterns and sets them, Make the 
windows, end inits in other variable that need to be set.) 


PROCEDURE DoSetup; 
VAR 


tempS : str255; 

tempR : rect; 

n : INTEGER; 
BEGIN 


appleMenu := GetMenuCeppleID); 
AddResMenu(appleMenu, ‘DRVR’); 
InsertMenuCappleMenu, 0); 


fileMenu := GetMenu(fileID); 
InsertMenuCf i leMenu, 0); 


editMenu := GetMenuCeditID); 
InsertMenuCeditMenu, 0); 


actionMenu := GetMenuCactionID); 
InsertMenuCactionMenu, 0); 


showMenu := GetMenuCshowID); 
InsertMenu(showMenu, 0); 


popupMenu := GetMenuCpopup 1D); 
InsertMenuCpopupMenu, - 1); 


DrewMenuBar ; 


ClearDishCOldDish); 
ClearDish(CurDish); 


SetMyColors(0, -1, -1, -1); 
SetMyColorsC1, 0, -1, -1); 
SetMyColors(2, 8, - 
SetMyColors(3, -1, -1, 0); 
SetMyColors(4, -1, 0, 0); 
SetMyColors(5, - 
SetMyColors(6, 9, 0, -1); 
SetMyColors(7, 0, 0, 0); 
CWhite.red := -1; 
CWhite.green := -1; 
CWhite.blue := -1; 


FOR n := Ø TO MaxAge DO 
BEGIN 
myPixMap[n] := NewPixPat; 
MakeRGBPat(nyP ixMap[n], myColors[n1) 
END; 


eboutWindow := GetNewCWindowCeboutID, NIL, POINTERC- 155; 
SetPor tColorsCaboutWindow); 


colorWindow := GetNewCWindowCcolorID, NIL, POINTER(-1)); 
SetPor tColors(colorWindow); 


GetIndStringCtempS, strID, 2); 
CenterRect(HQuick, VQuick, tempR); 
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quickWindow := NewCWindowCNIL, tempR, tempS, FALSE, 
noGrowDocProc, РОІМТЕКС- 1), TRUE, 0); 
SetPortColorsCquickWindow); 


GetIndString(tempS, strID, 1); 

CenterRectCHL ife, VLife, tempR); 

lifeWindow := NewCWindow(NIL, tempR, tempS, TRUE, 
noGrowDocProc, POINTERC-1), TRUE, 0); 

SetPortColorsClifeWindow); 


SetRect(bigRect, -32000, -32000, 32000, 32000); 
doneFlag := FALSE; 
END; 


(Standard Main Progrom Loop, loops til done flag is marked. 
Handles drags, go Aways, keys, end menu the same way. Updates 
and mouse downs in windows, call the specific routine to 
handle those events.) 


PROCEDURE MainLoop; 
VAR 


myWindow : WindowPtr; 
myChar : CHAR; 
myEvent : EventRecord; 
myPort : grafptr; 
BEGIN 
REPEAT 
SystemTask; 
IF GetNextEventCeveryEvent, myEvent) THEN 
CASE myEvent.what OF 
mouseDown : 
CASE FindWindow(myEvent .where, myWindow) OF 
inSysWindow : 
SystemClick(myEvent, myWindow); 
inMenuBar : 
DoCommand(MenuSe lect (myEvent.where)); 
inDrag : 
DragWindowCmyWindow, myEvent.where, bigRect); 
inGoAway : 
IF TrackGoAway(myWindow, myEvent.where) THEN 
HideWindow(mnyWindow); 
inContent : 
IF myWindow € frontWindow THEN 
SelectWindowCmyWindow) 
ELSE IF myWindow = lifeWindow THEN 
DoLifeClickCmyEvent . where) 
ELSE IF myWindow = colorWindow THEN 
DoColorC! ick(mnyEvent . where); 
OTHERWISE 
BEGIN 
END; 
END; 


keyDown, autoKey : 
BEGIN 


myChar :- CHRCBitAnd(myEvent.message, charCodeMask)); 
IF BitAnd(myEvent.modifiers, cmdKey) © Ø THEN 
DoCommand(MenuKey(myChar 22; 
END; 


updateEvt : 
BEGIN 

GetPortCmyPor t ); 

myWindow := WindowPtr(myEvent .message); 

BeginUpdate CmyWindow); 

SetPortCnyWindow); 

IF myWindow = lifeWindow THEN 
DoL if eDrew 

ELSE IF myWindow = colorWindow THEN 
DoColorDraw 

ELSE IF myWindow = aboutWindow THEN 
DoAboutDraw 

ELSE IF myWindow = quickWindow THEN 
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DoQuickDraw; 
EndUpdateCWindowPtr(myEvent .nessage 2); 
SetPor tCmyPort); 

END; 


OTHERWISE 
END; 


UNTIL doneF lag; 
END; 


(Main Program. First calls DoInit to do the standard inits. 
Then checks if Color Quickdraw Exists. If so, does Setup and 
Mainloop. If not, call DoSorry to explain.) 
BEGIN 
DoInit; 
IF ColorQDExists THEN 
BEGI 


DoSorry; 
END. 


UNIT ColorStuff ; 
INTERFACE 


ES 
ROM85, ColorQuickDrew, ColorMenuMgr, ColorWindowMgr, 
PickerIntf, myColorGlobals; 


PROCEDURE ClearDish (VAR J : Dish); 


PROCEDURE SetMyColors Ci, г, g, b : integer); 
PROCEDURE SetPortColors (W : windowptr); 
PROCEDURE CenterRect (h, v : INTEGER; 


VAR R : rect); 
PROCEDURE DoCommand CmResult : LONGINT); 
PROCEDURE DoColorClick (Where : point); 
PROCEDURE DoLifeClick (Where : point); 
PROCEDURE DoLifeDraw; 
PROCEDURE DoColorDrew; 
PROCEDURE DoAboutDrew; 
PROCEDURE DoQuickDrew; 
FUNCTION ColorQDExists : boolean; 


IMPLEMENTATION 


(Given Integer value Ccorrsponding to a string stored in STR! 
resource), drew that string, centered on point h,v in c 
color.) 
PROCEDURE DrewCenter (N, h, v, c : integer); 
VAR 
S : str255; 
BEGIN 
RGBForeColor(CmyColors([c12; 
GetIndString(S, strID, М); 
MoveToCh - (StringWidth(S) DIV 2), м); 
DrewStr ing(S); 
END; 


(Given a Dish, Clear all the cells (set to 0D.) 


PROCEDURE ClearDish; (Cvar J : Dish);} 


VAR 
h, v : integer; 


FOR h := Ø TO HEdgeMex 00 


FOR v := 0 TO VEdgeMex DO 
Jih, v] := 8; 
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(Given а Color Window Port, set the Pen апа Background color 
Patterns (stored in myPicMep in position Ø & 1, respec- 
tively).) 


PROCEDURE SetPortColors; (CW 
BEGIN 

SetPort(w); 

BackP ixPat(myPixMap [012; 

PenPixPatCmyP ixMap[1]); 
END; 


: windowptr ); } 


(Given & Color Window Port, calls SetPortColors to set Pen and 
Background color Patterns and forces on update by invalidating 
8 big Rectangle.) 


PROCEDURE ForceUpdate (W 
BEGIN 


SetPortColors(w); 
InvalRect(bigRect); 
END; 


: windowptr); 


(Given а Color Window Port, saves the current Port, calls 
UpdateOne and then restore the current port.) 


PROCEDURE UpdateOne (W : windowptr); 
VAR 
tempPort : grafptr; 


GIN 

GetPort( tempPort); 

ForceUpdate(w); 

SetPortCtempPort); 
END; 


(Saves the current Port, calls ForceUpdate for all the windows 
to update them all and then restore the current port.) 


PROCEDURE UpdateAll; 
VAR 
tempPort : grefptr; 


EGIN 
GetPortCtempPort?; 
ForceUpdateCaboutWindow); 
ForceUpdate(colorWindow); 
ForceUpdate(quickWindow); 
ForceUpdate(1ifeWindow); 
SetPortCtempPort); 
END; 


(Given а Color Window Port, if it is not in front Cor invis- 
ible), Shows it and Select it (make it the top window).} 


PROCEDURE ShowIt (W : windowptr); 
BEGIN 
IF FrontWindow <> W THEN 
BEGIN 


ShowWindow(W); 
SelectWindow(W); 
END; 
END; 


(Loads a new Dish and Dish Colors from disk. If successful, 
remakes the Dishes Color Patterns and updates all the windows 
Cusing UpdateAl1).} 


PROCEDURE DoLoed; 
VAR 


tempReply : SFReply; 

tempType : SFTypeL ist; 

tempP : point; 

Ref, n : INTEGER; 

tempE : OSErr; 

tempLong : longint; 
BEGIN 
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tempP.v := 49; 
tempP.h := 40; 
ќетпрТџуре [0] := FileType; 
SFGetFileCtempP, '^, NIL, 1, tempType, NIL, tempReply); 
Ref := 0; 
IF tempReply.good THEN 
BEGIN 


tempE := FSOpenCtempReply.fnaeme, tempReply.vrefnum, Ref); 
IF tempE = noErr THEN 
BEGIN 
tempLong := SIZEOFCDish); 
tempE := FSReed(Ref, tempLong, @CurDish); 
IF tempE = noErr THEN 
BEGIN 
tempLong := SIZEOF(CDishColor); 
tempE := FSRead(Ref, tempLong, @myColors); 
IF tempE = noErr THEN 
BEGIN 
tempE := 
Ref := 9; 
FOR n := 0 TO MaxAge DO 
МакеКбВРаїСтуР іхМар [п], myColors[n]); 
UpdateAll; 


FSClose(Ref ); 


END; 

IF Ref © 8 THEN 

tempE := FSClose(CRef ); 
END; 
END; 


(Save the current Dish and Dish Colors to disk.) 


PROCEDURE DoSeve; 


VAR 
tempReply : SFReply; 
tempP : point; 
Ref : INTEGER; 
tempE : OSErr; 
tempLong : longint; 
BEGIN 
tempP.v := 49; 
tempP.h := 40; 


SFPutFileCtempP, '^, °’, NIL, tempReply); 
IF tempReply.good THEN 
BEGIN 


tempE := FSDeleteCtempReply.fname, tempReply.vrefnum); 
IF CtempE = noErr) OR CtempE = fnfErr) THEN 
BEGIN 
tempE := CreateCtempReply.fname, tempReply.vrefnum, 
CreatorType, FileType); 
IF tempE = noErr THEN 
BEGIN 
tempE := FSOpenCtempReply.fname, tempReply.vrefnum, Ref); 
IF tempE = noErr THEN 
BEGIN 
tempLong := SIZEOFCDish); 
tempE := FSWriteCRef, tempLong, @CurDish); 
IF tempE » noErr THEN 
BEGIN 
tempLong := SIZEOFCDishColor); 
tempE := FSWriteCRef, tempLong, @myColors); 
IF tempE = noErr THEN 


BEGIN 
tempE := FSCloseCRef 5; 
Ref := Ø; 

END; 

END; 

END; 
END; 
END 


IF Ref о THEN 
tempE := FSClose(Ref ); 
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END; 
END; 


(Given а cells horiztonal and vertical position Cin cell 
position, not screen position), return the screen position 
Rectangle that contains that cell.) 


PROCEDURE MakeRect (h, v : integer; 
VAR R : rect); 


VAR 
n : integer; 

BEGIN 

n :* (h * Big); 

R.right := n; 

R.left := n - big; 

n := (v * Big); 

R.bottom := n; 

R.top := n - big; 
END; 


(Given a cells horiztonal end vertical position Cin cell 
position, not screen position) апа the correct screen rec- 
tengle holding that ce11,) drews the Cell in the correct 
pattern. It will only erase the cell if this call was not 
done by an update event Cupdate events erase everything). } 


PROCEDURE DrawRect Ch, v : INTEGER; 
R : rect; 
UpEvent : BOOLEAN); 
GIN 
IF CurDishIh, v] = 1 THEN 


PaintRectCR) 
ELSE IF (CurDishih, у] > 1) AND (CurDish[h, v] <= MaxAge) 
HEN 


FillCRect(R, myPixMapI[CurDish(h, v11) 
ELSE IF NOT UpEvent THEN 
EraseRect(R); 
END; 


(Given а point in the window where a mouse down occured 
(global coordinates), flips the cell at that point Cerasing 
one that there} or making on in an empty space). Then loops 
for every cell the} mouse pass over (drawing or erasing cells) 
until the button is released.) 
PROCEDURE бо! ifeClick; (CWhere : point?;) 
VAR 

h, v : integer; 

tempPort : grefptr; 

tempR : rect; 

empty : BOOLEAN; 


PROCEDURE CalcWhere; 
BEGIN 

h := (Where.h DIV big) + 1; 
(Where.v DIV big) + 1; 


у 
END; 


PROCEDURE DoDraw; 
BEGIN 
MekeRect(h, v, tempR); 
DrawRect(h, v, tempR, FALSE); 
END; 


PROCEDURE DoC1 ick; 
BEGIN 
IF Ch > Ø) AND Ch <= HEdge) AND (v > 0) AND Cv <= 
VEdge) THEN 
BEGIN 
IF Empty THEN 
BEGIN 
IF CurDishth, v] = Ø THEN 
BEGIN 
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CurDish[h, v] := 1; 
DoDrew; 
END; 
END 


LSE 
BEGIN 
IF CurDishth, v] © 0 THEN 
BEGIN 
CurDish([h, v) := 0; 
DoDrew; 
END; 
END; 
END; 
END; 


BEGIN 
GetPortCtempPort); 
SetPortClifeWindow); 
GlobalToLocal(Where); 
CalcWhere; 
empty := CCurDish[h, v) = 0); 
DoClick; 

REPEAT 
GetMouse(where ); 
CalcWhere; 
DoClick; 

UNTIL NOT Button; 


SetPort( tempPor t); 
END; 


(Given а mouse down point in the Color Window, display a pop 
up menu listing the RGB colors. If a color is selected, call 
the Color Picker (GetColor) to select а new color. If а color 
is picked, recalculate the Color Pattern (for that color) and 
Update al] the windows Cusing UpdateA11).) 


pee ee DoColorClick; (CWhere : point);)} 


tempLong : LONGINT; 
M, I : INTEGER; 
tempP : point; 
tempS : str255; 
ColorIt : RGBColor; 
BEGIN 
tempLong := PopUpMenuSelect(popupMenu, Where.v, Where.h, 12; 
M := HiWordCtempLong?; 
I := LoWordCtempLong) - 1; 
BED = popupID) AND (0 <= I) AND CI <= MaxAge) THEN 
N 


tempP.h := 0; 

GetIndStringCtempS, strID, 3); 

ColorIt := myColors[I]; 

IF GetColor(tempP, tempS, ColorIt, ColorIt) THEN 

BEGIN 
myColors[i] := ColorIt; 
MakeRGBPat(myPixMapli), myColors[i12; 
UpdateAll; 

END; 

END; 
END; 


(Draws 811 the cells in the Life window.) 
PROCEDURE DoL if eDrew; 
VAR 


h, v : integer; 
tempR : rect; 
BEGIN 
EraseRect(bigRect); 
FOR h := 1 TO HEdge DO 
FOR v := 1 TO VEdge DO 
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BEGIN 
MakeRect(h, v, tempR); 
DrawRectCh, v, tempR, TRUE); 
END; 
END; 


(Drews 811 the colors in the Color window.) 


PROCEDURE DoColorDrew; 
VAR 
tempR : rect; 
n, stert, finish : INTEGER; 
BEGIN 
SetRectCtempR, Ø, Ø, colorSize, colorSize); 
EreseRect( tempR); 
FOR n := 1 TO MexAge DO 
BEGIN 
start := (360 * (n - 1)) DIV MexAge; 
finish := (360 х n) DIV MaxAge; 
IF n = 1 THEN 


PaintArcCtempR, start, finish - start) 
ELSE 
FillCArcCtempR, start, finish - start, 


nyP ixMap[n1); 
END; 
END; 


(Draws the About Window Cinformation about the program and а 


spirograph type of desgin).} 


PROCEDURE DoAboutÜrew ; 
VAR 
h, v, n : INTEGER; 
BEGIN 
EraseRect(bigRect); 


TextSize(24); 

DrawCenter(4, HAbout DIV 2, 120, 7); 
DrewCenter(5, HAbout DIV 2, 150, 6); 
DrawCenter(6, HAbout DIV 2, 180, 5); 


FOR n := 1 TO StepSize - 1 DO 
BEGI 

h :* n * HStep; 

у n * VStep; 


PenP ixPatCmyP ixMap [4] ); 
МоуеТо(0, v); 
LineToCHAbout - h, 9); 


PenPixPatCmyP ixMap[31); 
MoveToCh, 0); 
LineToCHAbout, v2; 


PenP ixPatCmyP ixMap[21); 
LineToCHAbout, v); 
LineToCHAbout - h, VAbout); 


PenP ixPatCmyP ixMap[ 112; 
MoveToCh, VAbout); 
ГілеТо(0, v); 
END; 
END; 


(Draws the Quickdraw Window that displays the major Color 
Quickdraw commands (similer to the Lisa version).) 


PROCEDURE DoQuickDrew; 
VAR 
tempRect : Rect; 
tempPat : Pattern; 
tempPoly : PolyHandle; 
tempRgn : RgnHandle; 
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(Erase Background) 
EraseRect(bigRect); 

(Огаяв Squares) 
PenPixPatCmyP ixMap[ 112; 
MoveTo(9, 150); 

LineTo(458, 150); 
МоуеТос 150, 0); 
LineToC 150, 300); 
MoveTo(300, 0); 
LineToC300, 300); 

(Drews Titles) 

DrawCenter(7, 75, 20, 2); 
DrawCenter(8, 225, 28, 3); 
DrewCenter(9, 375, 20, 4); 
DrawCenter(19, 75, 170, 5); 
DrawCenter(11, 225, 170, 6); 
DrawCenter(12, 375, 170, 7); 

(Draw Rectangles) 

SetRectCtempRect, 15, 25, 95, 105); 
RGBForeColor(mnyColors[ 11); 
RGBBackColor (CWhite); 

PenPat (Black); 

FrameRect( tempRect ); 


OffSetRectCtempRect, QOff, QOff); 
RGBForeColor(CmnyColors (21); 
GetIndPattern(tempPat, 0, 31); 
PenPat( tempPat); 

PaintRect( tempRect); 


OffSetRectCtempRect, 0077, QOff); 
PenP ixPat(myP іхМәр (31); 
PaintRect( tempRect); 


OffSetRectCtempRect, QOff, QOff); 
RGBForeColor(CmyColors[4]); 
ВоВВаскСо1огСтуСо1огѕ [5 1); 
GetIndPattern(tempPat, 0, 32); 
PenPat(tempPat ); 
PeintRectCtempRect); 


OffSetRectCtempRect, 0077, 007Ғ); 

FillCRectCtempRect, myPixMap[612; 
(Оган Ovals) 

SetRect(tempRect, 165, 25, 245, 105); 

RGBForeColor(myColors[7]); 

RGBBackColor (CWhite); 

PenPat(Black); 

FremeOvalCtempRect); 


OffSetRectCtempRect, QOff, QOff2; 
RGBForeColor(nyColors[112; 
GetIndPattern(tempPat, 8, 33); 
PenPat(tempPat); 
PaintOvalCtempRect); 


OffSetRectCtempRect, QOff, 00ҒҒ); 
PenP ixPat(myP ixMap[21); 
PaintOvalCtempRect); 


OffSetRectCtempRect, QOff, 0077); 
RGBForeColor(myColors[3)]); 
RGBBackColor(myColors[4]); 
GetIndPetternCtempPat, 0, 34); 
PenPat( tempPat); 

PaintOval( tempRect ); 


OffSetRectCtempRect, QOff, 00ҒҒ); 
FillCOvalCtempRect, myPixMap[51); 


(Drew Round Rectangles) 
SetRect(tempRect, 315, 25, 395, 105); 
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RGBForeColorCmyColors[6]); 
RGBBackColor(Cwhi te); 
PenPat(Black); 
FrameRoundRect(tempRect, 20, 29); 


OffSetRectCtempRect, QOff, 00ҒҒ); 
RGBForeColor(mnyColors[7 12; 
GetIndPetternCtempPet, 0, 35); 
PenPatCtempPat?; 
PaintRoundRect(tempRect, 20, 20); 


OffSetRectCtempRect, QOff, QOff); 
PenP ixPat(CmyP ixMep[ 112; 
PaintRoundRect(tempRect, 20, 20); 


OffSetRectCtempRect, QOff, 0077); 
RGBForeColor(myColors[2)); 
RGBBackColor(myColors[3]); 
GetIndPatternCtempPat, 0, 36); 
PenPatCtempPat); 
PaintRoundRect(tempRect, 20, 20); 


Of fSetRect(tempRect, QOff, 00ҒҒ); 


FillCRoundRectCtempRect, 20, 20, myPixMap[4]); 


(Draw Polygons} 
tempPoly := heal 
SetRect(tempRect, 15, 175, 95, 255); 
MoveTo(95, 175); 
L ineToC65, 215); 
LineTo(95, 255); 
LineToC 15, 255); 
LineToC 15, 215); 
LineToC55, 175); 
LineTo(95, 175); 
ClosePoly; 


RGBForeColor(myColors[51]); 
RGBBackColor(Cwhi te); 
PenPat(Black); 

FramePoly( tempPoly); 


Of fSetPolyCtempPoly, 0077, QOff); 
RGBForeColor(myColors{6]); 
GetIndPattern(tempPat, 0, 37); 
PenPat( tempPat); 
PaintPolyCtempPo1y); 


OffSetPolyCtempPoly, QOff, QOff); 
PenPixPatCmyP ixMap(7 12; 
PaintPolgCtempPoly); 


OffSetPolyCtempPoly, 0077, 00ҒҒ); 
RGBForeColor(myColors( 11); 
RGBBackColor(myColors[2]); 
GetIndPetternCtempPat, 0, 38); 
PenPat( tempPat ); 
PaintPolyCtempPoly); 


OffSetPolyCtempPoly, 0077, 0077); 
FillCPolyCtempPoly, myPixMap[31); 


KillPolyCtempPoly); 


(Draw Arcs) 
SetRectCtempRect, 165, 175, 265, 275); 
RGBForeColor(myColors[41]); 
RGBBackColor(Cwhite); 
PenPat(Black); 
FrameArc(tempRect, 198, 72); 


RGBForeColor(myColors[5]); 
GetIndPatternCtempPat, 0, 15); 
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PenPatCtempPet); 
PeintArcCtempRect, 126, 72); 


PenP ixPat(myP ixMap[61); 
PaintArc(tempRect, 270, 72); 


RGBForeColor(myColors(7]); 
RGBBackColorCmyColors[1]); 
GetIndPattern(tempPat, 0, 16); 
PenPat( tempPat); 
PeintArcCtempRect, 342, 72); 


OffSetRectCtempRect, 20, 9); 
FillCArcCtempRect, 54, 72, myP ixMap 21); 


(Draw Regions} 
tempRgn := NewRgn; 
OpenRgn; 
SetRect(tempRect, 315, 175, 395, 255); 
FrameRoundRect(tempRect, 20, 20); 
InsetRectCtempRect, 10, 10); 
FremeOvalCtempRect); 
CloseRgn( tempRgn); 


RGBForeColor(mnyColors (31); 
RGBBackColor (CWhite); 
PenPat(Black); 

FrameRgn( tempRgn); 


OffSetRgnCtempRgn, QOff, 0ОҒҒ); 
RGBForeColor CmyColors(4)); 
GetIndPatternCtempPat, 0, 17); 
РепРа(СЧепрРа(); 

PaintRgn( tempRgn); 


OffSetRgnCtempRgn, 0077, QOFF); 
PenPixPetCmyP ixMap (5 1); 
PaintRgnCtempRgn); 


OffSetRgnCtempRgn, QOff, QOff); 
КоВЕогеСо1огСтуСо1огѕ (61); 
RGBBackColor(myColors[71]); 
GetIndPattern(tempPat, 0, 18); 
PenPetCtempPat); 
PaintRgnCtempRgn); 


OffSetRgnCtempRgn, QOff, 0077); 
FillCRgnCtempRgn, myPixMap[ 112; 


DisposeRgnCtempRgn); 
END; 


(Steps through а generation of growth/death of the Dish. 
Stores the old Graf port, then sets the Life window as the new 
one. Copies the current dish into the old dish, then checks 
each cells one by one. Calculates the number of cells around 
it, end decides deaths, lifes and births. If the new value 
does ыы match the old value) Cie. change), redraw that 
window. 


PROCEDURE DoStep; 
VAR 


n, h, v, c : INTEGER; 
tempPort : grefptr; 
tempR : rect; 
BEGIN 
GetPor tC tempPor t); 
SetPor tC] ifeWindow); 
BlockMove(@CurDish, @01dDish, SIZEOF(Dish2); 


FOR h := 1 TO HEdge DO 


FOR v := 1 TO VEdge DO 
BEGIN 
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n :* 0; 
IF OldDishIh - 1, v - 1) © 0 THEN 


п := п + l; 

IF 01dDishth, v- 1] © 0 THEN 
п:=п+ 1; 

IF OldDishth + 1, v- 1] © 0 THEN 
п:=п+ 1; 

IF ланам - 1, v] © 0 THEN 
п = п + l; 

IF OldDishth E 1, v] 9 0 THEN 
niant l; 

IF O1dDishth - 1, v+ 1] © 0 THEN 
n:e=nt l; 

IF OldDishth, v + 1] © Ø THEN 
п = п + 1; 

IF OldDishth + 1, у + 1) © 0 THEN 
n =n+ 1; 


= QldDishth, v]; 
IF (c = 0) AND (n = 3) THEN 
CurDishíh, v] := 1 
ELSE IF (с o Ø) AND (Cn = 3) OR (n = 2)) THEN 
BEGI 


N 
IF c « MexAge THEN 
CurDish[h, v] := c+ 1; 


ELSE 
CurDish([h, у) := Ø; 


IF CurDishth, v) © c THEN 
BEGIN 
MakeRectC(h, v, tempR); 
DrawRect(h, v, tempR, FALSE); 


END; 
SetPortCtempPort); 
D 


д 


(Standard Menu Command command procedures. Takes card of Desk 
Accessories, About (show About Window), New (clear jar апа 
update Life window), Load/Save (call DoLoad/DoSave), Quit 
(mark Done Flag), Action Menus (Step, Step 10 Times or Step 
until а Mouse down) and Show Menus (show one of the 3 other 
windows). } 


PROCEDURE DoCommand; (CmResult : LONGINT);) 
VAR 
theItem : INTEGER; 
theMenu : INTEGER; 


name : Str255; 
temp : INTEGER; 
tempBool : BOOLEAN; 
tempEvent : EventRecord; 
BEGIN 
theItem := LoWord(mResult); 
theMenu := HiWord(mResult); 


CASE theMenu OF 
eppleID : 
IF CtheIten = 1) THEN 
Show! tCaboutw indow) 
ELSE 
BEGIN 
GetItemCappleMenu, theltem, name); 
temp := OpenDeskAcc(name); 


c thelten OF 
BEGIN 


CleerDishCCurDish); 
UpdateOneC1ifeWindow); 


4 
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DoLoad; 
DoSave; 


doneF lag := TRUE; 
OTHERWISE 
ND; 
editID : 
tempBool := 
ectionID : 
е theIten OF 


Dostep; 


“FOR temp := 
DoStep; 


3: 
WHILE NOT ёс шыша tempEvent) DO 
DoStep; 
OTHERWISE 


showID : 
е. thel tem OF 


SystemEdit(theItem - 1); 


1 TO 19 DO 


"Show! t(1ifeWindow); 
2: 

ShowItCcolorWindow); 
3 . 


Show! tCquickWindow); 
OTHERWISE 
END; 
OTHERWISE 
END; 
HiliteMenuC0); 
END; 
(Checks if Color Quickdraw Exists on this machine.) 
FUNCTION ColorQDExists; ( 
CON 


ST 

ROM85Loc = $28E; 

TwoHighMask = %С000; 
VAR 

WordPtr : “Integer; 

ROM85Value : integer; 


: boolean; )} 


BEGIN 

WordPtr := pointerCROM85Loc); 

ROM85Value := WordPtr^; 

ColorQDExists := (Bi tAnd(ROM85Value, TwoHighMask) = 0); 
END; 


(Given а h әла v size, calculates a Rectangle that is centered 
on the screen.) 


PROCEDURE CenterRect; (Ch, v : INTEGER; ver R : rect?;) 
VAR 
Hoff, Voff : INTEGER; 
BEGIN 


Hoff := (ScreenBits.bounds.right - h) DIV 2; 
VOff := (ScreenBits.bounds.bottom - v) DIV 2; 
IF voff « 35 THEN 
VOff := 35; 
SetRect(R, Hoff, VOff, Hoff + h, Voff + v); 
END; 


(Given RGB values (3 integers) and pos (which , places the 
values in the Dish Color in the correct position.) 
PROCEDURE SetMyColors; (Сі, r, 0, b : integer2;) 
BEGIN 
myColorslil.red := г; 
nyColors[il.green := g; 
myColors[i].blue := b; 
END; 
END. 
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UNIT myColorGlobals; 
INTERFACE 


USES 
ColorQuickDraw; 
(Constants: various Resource IDs, File Type and Creator 
Signitures, Maximum recorded Age of Cell, Horizontal/Vertical 
size of Dish (containing cells), Size of cells, Size of other 
windows and other size information.) 
CONST 


eppleID = 256; 
fileID = 257; 
editID = 258; 
ectionID = 259; 
ShowID = 260; 
popupID = 261; 


strID = 256; 

sorryID = 256; 
aboutID = 256; 
colorID = 257; 


FileType = ‘life’; 
CreatorType = ‘life’; 


MaxAge = 7; 

VEdge = 59; 

VEdgeMax = 51; 

HEdge = 70; 

HEdgeMax = 71; 

Big = 8; 

VLife = 400; (Big * VEdge) 
HLife = 560; (Big * HEdge) 


VQuick = 300; 
HQuick = 450; 
QOff = 10; 


colorSize = 300; 
StepSize = 30; 


HStep = 20; 
VStep = 10; 
HAbout = 600; (StepSize * HStep) 


t = 
VAbout = 300; (StepSize * VStep) 


(Types: Age range, Dish info (containing 811 cells & age), 
Dish Colors (containing RGB colors), Dish Color Patterns (RGB 
info converted to a Color Pattern).) 
TYPE 
Аде = 0. .MaxAge; 
Dish = PACKED ARRAY[Ø. .HEdgeMax, 8..VEdgeMax] OF Age; 
DishColor = PACKED ARRAY[@..MaxAge] OF RGBColor; 
DishPixMap = PACKED АКБАҮ(0. .MaxAge] OF PixPatHandle; 


(Variables: Menus Cincluding PopupMenu), Windows, RGB Colors, 
Color Patterns, large Rect Cused for drag & updates), Done 
Flag end Current & Øld Dishes.) 
VAR 

appleMenu, fileMenu, editMenu, actionMenu, showMenu, 
popupMenu : MenuHendle; 

lifeWindow, aboutWindow, colorWindow, quickWindow : 
WindowPtr; 

myColors : DishColor; 

myPixMap : DishPixMap; 

bigRect : Rect; 

doneFlag : BOOLEAN; 

OldDish, CurDish : Dish; 

CWhite : RGBColor; 


IMPLEMENTATION 
END. 
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* Life.R 

* Resources for Color Life 

x 0 1987 by Steve Sheets for MacTutor 
x 


x 
Life.RSRC 


Type LIFE = STR 
0 


Color Life Application - Version 1.8 by Steve Sheets 


Type FREF 
, 128 (Ø) 
APPL 0 
, 129 (0) 
LIFE 1 


Type BNDL 

, 128 (0) 
LIFE @ 
ICN' 
0 128 1 129 
FREF 
0 128 1 129 


TYPE STR 
,256 
12 
Life 
Quickdrew 
Select Color: 
Color Life by Steve Sheets 
Demo of Color Quickdraw 
on the Mac // 
Rectangles 
Ovals 
RoundRectangles: 
Arcs 
Polygons 
Regions 


TYPE WIND 

,256 
About Life 
40 20 340 620 
Invisible Goaway 
4 
0 


ТҮРЕ WIND 

,251 
Colors 
40 170 340 470 
Invisible Goaway 
4 
"| 


* Menus 

з 10 Cettributes) 

x menu title Can Apple symbol is \ 14 in hex) 
* menu items, ( means it’s initially disabled. 
* (- means a disabled line of dashes. 

х A trailing /Q, etc. means a command-key. 
Type MENU 


Type MENU 
‚251 

File 

New 
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Load 256 
Save 4444 


Quit/Q * A Dialog or Alert Item List 
x „ID Cattributes) 


Type MENU * number of items in list 
,258 * type of item 
Edit * top left bottom right 
Undo/Z * message 
(- Type DITL 
Cut /X ‚256 
Сору/С 2 
Paste/V 
Clear button 
60 120 80 180 
Туре MENU OK 
,259 
Action staticlext Disabled 
Step/S 20 10 40 290 


Ten Steps/T 


Sorry, this progrem only runs on а Mec // 
Loop til Button/L 


* misc resources 


Type MENU 
,260 * An icon list for the icon 
Show х „ID Cettributes) 
Life х Data is Hex data С.Н) 
Colors * the icon data: 32 lines of 8 hex chars each 
Quickdraw * the icon mask: 32 lines of 8 hex chars each 
Type ICN® = GNRL 
Type MENU ,128 (Ø) 
,261 H 


0000 0000 ЕЕ00 OEEE ЕЕ00 OEEE ЕЕ00 OEEE 
0000 0000 Е000 000Е Е000 000Е Е000 BOE 
0000 0000 BOGE 00Е0 000Е 00-0 BOGE 00Е0 
0000 0000 O0tE 0000 00ЕЕ 0000 00ЕЕ 0000 
0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 SEED 0000 OCEO 0000 BEEG 0000 
Select Age 5 Color 0000 0000 EGJE 00ЕЕ EGJE 00ЕЕ EGJE 00ЕЕ 
Select Age 6 Color 0000 0000 SEES OOEE SEED 00ЕЕ BEEG BEE 
Select Age 7 (&older] Color * [2] 
0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
х — Dialogs —— 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
* Progrem Messages Dialog box... 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
type DLOG 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
,251 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
Progrem Messages 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 
100 100 200 400 0000 0000 EEEE EEEE EEEE EEEE EEEE EEEE 


X 

Select Background Color [Age 9] 
Select Foreground Color [Age 11 
Select Age 2 Color 

Select Age 3 Color 

Select Age 4 Color 


Visible NoGoAway 
1 


0 x 10 Cattributes) 
257 з Data is Hex data С.Н) 
x the icon data: 32 lines of 8 hex chars each 
type DITL * the icon mask: 32 lines of 8 hex chers each 
,251 Type ICN* = GNRL 
3 ,129 (0) 
BtnItem Enabled ‚Н 
65 230 95 285 IFFF ҒС00 1000 0600 1000 0500 1000 0480 
OK 1000 0440 1360 3420 1360 37FØ 1000 0010 
1300 0000 1300 0000 1000 0010 1001 8610 
StatText Disabled 1001 8610 1000 0010 1000 8010 1000 8010 
15 60 85 222 1000 0010 1000 0010 1000 0010 1000 0010 
0/00: 11007210073 106С 0010 106С 0010 1000 0010 1301 8600 
1301 8600 1000 0010 106С 0600 106С 0600 
IconItem Disabled 1000 0010 1000 0010 1000 0010 1РЕР FFFO 
10 10 42 42 ж (21 
1 IFFF ҒС00 ІҒЕҒ ҒЕ00 1FFF РЕ@@ 1FFF FF80 
IFFF ҒҒСй 1FFF FFEO 1FFF FFFØ 1FFF FFFO 
z — Alerts IFFF FFFØ 1FFF FFFØ 1FFF FFFØ 1ЕРЕ FFFØ 
IFFF FFFØ 1FFF FFFØ 1ЕРЕ FFFØ 1FFF FFFØ 
* Program error alerts... 1РЕЕ FFFØ 1FFF FFFØ 1FFF FFFØ 1FFF FFFO 
type ALRT IFFF FFFØ 1FFF FFFØ 1FFF FFFØ 1FFF FFFO 
,256 IFFF FFFO 1FFF FFFO 1FFF FFFO 1FFF FFFO 
40 106 140 406 IFFF FFFO 1FFF FFFO 1FFF FFFO 1FFF FFFO 
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* Àn icon list for the icon 


MacApp Objects 


Programming in the Closet 


or 
"How to write a program without really writing a 
program" 

Dave Wilson is the owner of Personal Concepts, a consult- 
ing firm specializing in software development for the Macin- 
tosh. He currently is teaching courses for Apple on both 
beginning Macintosh programming and object-oriented 
programming. 

This article can be blamed on Howard Katz, who is the 
newsletter Editor for the MacApp Developer's Association. 
Howard knew that I present four-day Seminars for Apple entitled 
MacApp™ and Object Oriented Programming ,and thought that 
experiences from the first five of these seminars might be useful 
to others who are learning MacApp. Much of this article first 
appeared іп the May 1987 issue of the MacAppDA's newsletter, 
and is reprinted with their permission. I might add that you 
should definitely join us in the MacAppDA if you haveaninterest 
in object-oriented programming for the Macintosh. Y ou can join 
by sending $15.00 to: 

MacApp Developer's Association 

P.O. Box 23 

Everett, WA 98206-0023. 


First, some background to put the article in perspective. Ihave 
taught Apple's beginning Macintosh Programming Seminars for 
the last two and one-half years, and have developed a healthy 
respect for the difficulties of writing Mac applications during this 
time. Starting about two years ago, I began to hear about this 
strange beast called MacApp that was claimed to make Mac 
programing relatively easy, so I got a copy to try out. 

I didn't begin seriously learning to use it until last Fall, when 
Apple agreed that a monthly Seminar was needed to help people 
get up to speed quickly on this new and powerful tool, so I started 
learning MacApp with more urgency. It took me about three 
man-months to feel comfortable with it, and the seminar is 
designed to fit as much of those experiences as possible into four 
days. 

By the way, Apple also decided to provide a separate one-day 
seminar on Using MPW the day before each MacApp class, so we 
could cover Make files, Rez, etc. before worrying about MacApp 
itself. More about that below. By now you should be wondering 
if I am ever going to explain the weird title, so here goes... 

A History Lesson 

А long, long time ago, in an operating system far, far away, 
applications programmers wrote code that directed the user along 
acertain path. As the programmer, you were clearly in control of 
what happened, so you gave orders to the user, and the user did 
what he or she was told. If the user did not follow orders, you 
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= 


Pascal 


displayed friendly error message suchas “Syntax Error 5", 
and hoped the user would shape up. 

Then the Macintosh came along, and you were instructed to 
write friendly, “modeless” programs, with the operation con- 
trolled by the user. (Incidentally, humor writer Dave Barry 
defines "User" as the word that programmers use when they 
mean "idiot"). You wrote modeless programs by basing your 
application on a Main Event Loop. This had you calling the 
GetNextEvent ROM routine, and responding accordingly to 
events caused by the user. I liken this to programming in a room 
with the door closed. You can't see the user, but when the user 
clicks the mouse down or types a key, the Event Manager slides 
a piece of paper under the door that contains the Event Record. 
You read the piece of paper, and respond accordingly. 

Some programmers who are new to the Macintosh feel a bit 
nervous with this style because they don't feel in control, but 
users certainly prefer it - because they are in control. 

What happens with MacApp? It gets even worse. MacApp is 
an expandable generic application, consisting of hundreds of 
pages of Object Pascal source code written by some of Apple's 
best programmers. All you have to do is customize the applica- 
tion through the special hooks provided by object-oriented pro- 
gramming, and, presto: you have your program! 

Are you still all alone in the room, looking at pieces of paper 
slid under the door by the Event Manager? Uh-uh, MacApp is. 
Where are you? You are in the closet. Most of the time the 
program runs without needing your code at all, so MacApp will 
handle moving and resizing windows, operating scroll bars, 
opening Desk Accessories, etc. Once in a while MacApp needs 
you to do something specific to your program, so it opens the 
closet door, barks at you to “Draw yourself" or “Save the data to 
disk", and then closes the door. You just do what your told, and 
stay out of the way the rest of the time. 

With MacApp, you are no longer writing an applications 
program, but rather you are writing a few code fragments that 
customize the generic program written by Apple. Apple's code 
runs the Main Event Loop, and does most of the event handling, 
SO be sure to take a good book in the closet, because most of the 
time, you won't have anything to do. 

Your only problem will be in learning to use MacApp, and 
getting used to this new style of writing code. Which brings us... 

Back to the Seminars 

Who takes these seminars? So far, we have had programmers 
from large corporations and universities, independent develop- 
ers, Apple systems engineers, and Apple internal software devel- 
opers. I expect to see many VARs (Value Added Resellers) and 
consultants during the next year - particularly as the powerful 
Macintosh II stimulates new interest in programming the Mac. 
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The MacApp seminar itself is a mixture of lectures and hands- 
on labs. We probably spend about 25% of the first two days 
programming, and perhaps 50% of the last two days. Each person 
has a Mac Plus with an HD-20 or HD-20SC with MPW and 
MacApp installed to use during class. We also provide some new 
sample programs and a 500-page Notebook. 

The programming Labs begin with the Nothing program 
provided by Apple as a standard MacApp sample. You then add 
features to this program over the next four days until you have a 
texteditor that, just for fun, can draw rectangles on top of the text. 
A palette controls part of the program's operation, and the text 
and graphics can be saved to a document file on disk. This 
process is described in a 13-part exercise that you work on for the 
whole four days - at your own pace. The majority of people will 
not finish this project during class, but do leave with the “solu- 
tion" on disk, so they can finish it on their own if they wish. A 
screen dump from the finished Lab is shown below in figure 1. 

At this point, you might ask “Is MacApp easy to learn?”, and 
I would have to answer a definite "maybe". Perhaps 25% of the 
students so far find that they are writing MacApp programs 
within four days. The other 7596 find that they know much more 
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Fig. 1 Getting into Objects In the Class Lab 


about MacApp, but still feel that they need to invest more time on 
their own before they are ready to write a program. The major 
obstacle seems to be learning the new style and behavior of 
object-oriented programming, so people who have had experi- 
ence with SmallTalk, Neon, Common LISP, etc. have a much 
easier time. 

In the rest of this article, I'll mention some of the common 
stumbling blocks, and suggest ways around them. This article 
will be most useful to you if you have already tried to learn 
MacAppon yourown, andare having problems with understand- 
ing certain concepts. If you have never seen MPW or MacApp, 
you might want to read MacTutor's introductory articles pub- 
lished in back issues first. 

MPW 
MPW (the Macintosh Programmer's Workshop) seems to be 
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easy for people to handle because of MacApp's nifty MABuild 
command. There are a couple of things to keep in mind, however. 

Remember to update your Make file when you use new 
building blocks (such as the text edit Unit UTEView), or new 
files containing resources (such as you might make with Re- 
sEdit). Otherwise, MABuild will not update everything properly 
if changes are made to these files. 

MENU resources are not directly used in MacApp, so we 
instead need to use command menus, of resource type 'cmnu'. 
These are easy to describe ina text file for Rez, as long as you can 
figure out which items to enable. The golden rule is that the least 
significant bit in the enable flag should be set to 1 to enable the 
first item in the menu, the next bit controls the second menu item, 
and so forth. 

Object Orlented Programming 

The major obstacles involve object-oriented 
programming(OOP), rather than Object Pascal or the MacApp 
libraries. Here are some of the common problems: 

Program Design 
Almost everyone has a hard time deciding which object types 


should be defined for the program that they wish to write. We 
spend a few hours in class on this subject, so I can’t 


make a simple answer here, but I'll suggest a partial 
method to use (notice the great pun). 

Step 1: Decide on what types of documents you need 
on disk. These will then correspond to your Document 
object types. For example, you might have text docu- 
ments that will be displayed in windows, and Index 
documents that the user never manipulates, but that are 
used by data base access routines. 

Step 2: Decide what views of your document’s data 
are to be shown in the windows. These will correspond 
to your View object types. For example, you might 
have a text view of your text document, a tabular view 
of some data base information, and a palette view that 
the user can use to control the program’s operation. 
Note that the palette view may not be associated with 
any specific document. 

Step 3: Decide what data objects you need to ma- 
nipulate. These might represent graphics objects, 


“customer” objects, or other objects that you might have formu- 
lated as Pascal Records in an earlier life. You still may decide to 
keep customer information in a record, but it is often better to 
create an Object Type, since you can then associate the methods 
that operate on the customer with the data about the customers. 
INHERITED vs. SELF 

A great strength of OOP is that we can Override a method, and 
substitute a new version of it with modified behavior. Acommon 
approach is to then reuse the old behavior in the new method by 
using the Object Pascal keyword INHERITED. This tells the 
program to use the ancestor’s method. Another common tech- 
nique is for an object to call one of it’s own methods, using the 
optional keyword SELF. 

That all sounds simple, but most people get confused as to 
when to call SELF.DoMenuCommand, and when to call 
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INHERITED.DoMenuCommand, and in fact I have even been 
guilty of writing 


INHERITED SELF .DoMenuCommand; 


in my code. Not good. The rule to remember is that you use 
INHERITED to call a method of the ancestor to the object, while 
SELF refers to a method (or field) of the current object type. 
Out of sight, out of mind 
When you define an Object Type in the Interface of your Unit, 
you only define changes to the Object Type. Consider the 
example below: 


TMyView = OBJECTCTView) 
TMyV iew. IMyView; 
TMyView.DrawCarea:Rect); OVERRIDE; 
END; 


This looks so simple that people often forget that an object of 
type TM yView also has all the fields and methods of TView, so 
that INHERITED Draw is definitely different than SELF Draw. 
Furthermore, they forget that an object of type TM yView now has 
method /View in addition to method JMyView. It even has the 
method /EvtHandler that is inherited from the ancestor of TView. 

This confusion leads to various strange things in people's 


code, so remember that everything that we don’t override does 
get inherited from all the ancestors, including the ancestors of the 
immediate ancestors. 
Fields that refer to other objects 

A typical Interface might include the following: 
TMyDocument = OBJEC TCTDocument ) 

fMyView: TMyView; 

TMyDocument.DoMekeViews; OVERRIDE; 

etc. 


TMyView = OBJECTCTView) 
fMyDocument: TMyDocument 
etc. 


I find that people (a) often do not understand why they should 
include these cross-references, and (b) often forget to stuff 
correct values into these fields. 

You should save a reference to an object so you can easily 
refer to a method or field of that object. You should then 
remember to initialize these fields with the proper values. If you 
do not, your program will crash into the MacApp interactive 
debugger with MacApp's most common error, which is an ID = 
03 crash. This usually means that your program is trying to use 
a field or method of an object that has an invalid address (i.e.,, an 
object reference that has never been initialized). 

Inheritance Tree vs. Creation tree 

Some people get confused about tree diagrams, since you may 
see more than one type. A typical inheritance diagram might look 
the one below, in figure 2, which means that TList, TCommand, 
and TEvtHandler each inherit all the fields and methods of 
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TObject. 

On the other hand, you might sometimes see a diagram that 
shows which objects create other objects, such as shown below 
in figure 3. 


The confusion arises because people may think that the latter 
diagram represents property inheritance, rather than creation 
order. Remember, just because your application object creates 
your document objects does not imply that documents are 
descendents of applications. 

initialization methods 

You need initialization methods to stuff correct values into 
the data fields of your object. This can be confusing because 
MacApp provides a number of initialization methods that you 
mustcall, but you usually also define some of your own. And, you 
should follow a certain style convention in doing this. 

Consider defining a type of object TMyView that it a descen- 
dent of TView. That means that TMyView inherits an [View 
method. Now should you (1) use View, (2) Override [View, or 
(3) define an new initialization method /MyView? The correct 
answers are “yes”, "no", and “yes”. Let's see why. 


Tobject | 


TCommand | ux 


Handler 


Fig. 2 Inheritance from TObject 


TMyApplication 


.DoMakeDocument 


TMyDocument 


.DoMake Views NewSimplewindow 


.DoMouseCommand 


TSketcher 


Fig. 3 Objects from Objects 


If your new Object Type has no new data fields to initialize, 
you may just want to use the following: 


NewCaView): 
FailNilCaView); 
eView.IViewC..2; 
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If your new Object Type does have data fields, you should not 
Override View, but rather define a new method JMyView, and 
. callIView from within that method. Why? Because if you keep 
IView and IMyView as separate methods, and never Override 
either one anywhere in your program, the compiler/linker can 
optimize them to be called as normal procedure calls rather than 
method calls. This will take place if you compile your program 
with the Optimize option turned on, and will improve perform- 
ance and reduce overhead. 


The MacApp Object Library 


Managing all the goodies provided by MacApp. 

We use a quick reference guide to MacApp when working in 
class, as an easier method to access all of MacApp Constants, 
Globals, fields, methods, etc. This Quick Reference is in the class 
Notebooks, but I will probably arrange for A.P.D.A. to distribute 
this so others can use it. 

I also use a recipes file that contains sample Implementations 
to commonly used MacApp methods such as DoMenuCom- 
mand, TrackMouse, ITEView, etc. I usually work with this file 
open in MPW and liberally steal from it. This saves having to 
type the long parameter lists that many of these routines need. 

The MacApp Developer's Association is now selling a 
Browser Desk Accessory, modeled after the Browser in Small- 
Talk, that should be of great help in accessing the source code. 


Drawing in the wrong methods 


A common mistake is to draw on the screen in other methods 
than your view object's Draw method. 

Ап advantage to having Draw do all the work is that both 
screen updating and printing call the draw method. If you were 
to instead call QuickDraw graphics routines from other methods, 
then your drawings may not appear after screen updates, or on the 
printouts. 

Another advantage to using the Draw method is that MacApp 
will first call TFrame.Focus method before calling Draw. The 
Focus method insures that the origin and clip region are properly 
set. If this is not called, you may find that drawing takes place in 
the wrong part of your view, or that you draw all over the scroll 
bars - which you will find to be both ugly and embarrassing. 

The best technique is usually to have other methods invalidate 
aregion orrectangle in the view, and then wait foran update event 
to force your view object to draw itself. It is, of course, perfectly 
O.K. to have your Draw method ask individual objects to draw 
themselves, as is done in the DrawShapes sample program. If 
you can't wait for an update event, be sure to call Focus before 
calling Draw. 


The mysterious command object 
Command objects are very difficult for newcomers to 


MacApp to understand. People are usually pleased when I tell 
them that they can ignore command objects if they do not wish 
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toimplement Undo. Unfortunately, you should implement Undo 
for any operation that changes the data in a document, and 
therefore you often should use command objects. 

What are command objects? They are merely temporary 
objects that save enough information so that the last operation 
can be undone. Keep in mind is that MacApp will call the 
methods of TCommand at certain times during the operation of 
your program. All you have to learn is when these methods will 
be called, and whatany OVERRIDEs of these methods should do 
when they are called. 

For example, MacApp will call the current command object's 
Dolt method after a menu item is chosen by the user. All you have 
to do is create the command object in your DoMenuCommand 
method, and then have a DoIt method to do what you want done 
in response to that menu command. What could be easier? Don't 
answer. 


Some methods create command objects 


This brings up another source of confusion. There are three 
common methods that create command objects: 
DoKeyCommand, DoMouseCommand, and DoMenuCommand. 
These are not methods of command objects, but merely methods 
that create new instances of command objects. For example, 
TYourView.DoMouseCommand may create an object of Type 
TSketcher, soitis TSketcher that needsa Dolt method, not TView. 


Frames, views, and windows 


Itiseasy to get confused as to the difference between a frame, 
a view, and a window. Consider the screen dump shown below 
in figure 4. 


The resizable window contains a large, resizable frame which 
displays part of a view of type TParentView. There are three 
smaller frames installed in the large frame, and each frame has 
it’s own set of scroll bars (you can see that the scroll bars clearly 
belong to the frame, and not the window). Each frame displays 
part of a view, with the frame being a “porthole” through which 
the user can see part of what might be a very large view. 

By the way, the key to handling more than one view in a 
window is to remember that each view lives in its own coordinate 
system, with each origin at (0,0). Resist the temptation to offset 
the origin just because the view will live in a frame in the middle 
of the window. The frame's job is to take care of the origin - all 

view n i nd it} nly view in the wor 

Using TextEdit objects 

Itis easy to use a view of type TTEView, and create acute little 
text editor with only a few lines of code. The tricky part is 
remembering to add UTEView to your USES statement in both 
your Unitand in the main program. If you forget this, you will get 
compiler error messages that mumble about there being no 
methods of that type for this object, and so forth. What we need 
is a compiler that says "Hey dummy, you forgot to add the 
UTEView Unit to the Uses statement!" Perhaps in version 2.0... 
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When will MacApp call its methods, and 
will it ever call yours? 


A major source of confusion has to do with how 
MacApp works. MacApp is based on hundreds of 
pages of source code, written in the OOP style, 
leading to what Howard Katz called “ a futile search 
for where the buck stops". This means that newcom- 
ers to MacApp have to deal with a mysterious pro- 
gram that calls hundreds of its methods when it feels 
like it, and you often do not know when that is going 
to be. There is a rule to guide us, however. 

The Rule: MacApp can only call methods that are 
definedas part of MacApp. This meansthat MacApp 
will call the DoMouseCommand method for a view, 
if that view is the “target”. This DoMouseCommand 


method will be the one provided with MacApp if you have not 
Overriden it, but it will be your DoMouseCommand if you have 
done an Override. The Rule also means that MacApp will never 
call the /YourDocument method that you created to initialize 
objects of type TYourDocument, because that method was un- 
known to the people who wrote MacApp. Remember Wilson’s 
Conjecture: MacApp is just computer code - its not magic. 

The Rule, Part B: When you define new types of objects, with 
new methods, you are providing a set of tools for MacApp and 
you to use. When you Override an existing method, you are, in 
a sense, leaving that customized tool on the table for MacApp to 
use, and MacApp will generally use that tool when appropriate. 
When you define a method that is unique to your program, then 
MacApp cannot use that tool, so it is up to you to use it when 
necessary. 


Andy Seligman’s Poem 


The following poem was written by a student in the first 
MacApp class. It makes MacApp sound challenging, which it is, 
but it will show you that we have interesting and talented people 
leaming MacApp. 


There was a young hacker from Apple 

Who haplessly started to grapple 

With Windows and mice, and Inside Mac vice 
He thought “User Friendly’s not nice!” 


He told his boss of his confusion, 

Who answered “I see that your usin’ 

Old coding technique, that’s now quite antique, 
I'll send you to class all next week!” 


He went there to master MacApp, 

but soon realized his mishap, 

The instructor strode in and proclaimed with a grin 
Ican talk longer than you can listen! 
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=== Untitled-1 == 


He froze as he sat in the room, 

and felt with a keen sense of gloom 
“The problem with me, is I can not see 
Which object sends what and to whom." 


He labored until his mind reeled, 

through Object and Method and Field, 

The class was sure great, but now he can't wait, 
To read Dave's book MacApp Revealed! 


Conclusion 


What should we conclude from all this? I feel that MacApp 
is a bit tricky to learn to use, but I also feel that it is well worth the 
investment. I haven't dwelled on the advantages to using 
MacAppin this article, but they are very compelling. MacApp's 
value lies in four major areas: 

(1) You can geta complete Mac application running in much 

less time than if you use traditional development system, 

(2) The user interface will conform very well to Apple's 
recommendations, 

(3) The MacApp code follows the compatibility guidelines, 
so that your application will run unchanged on everything 
from an old Mac 512K to a Macintosh II, and 

(4) The program will be relatively bullet-proof, in that most 
errors will generally be trapped by the error handling 
routines. This latter point is often overlooked, but it is 
much better to present the user with an alert box that says 
that the window cannot be opened because of a lack of 
memory, instead of the program crashing with the dreaded 
bomb. 

For those who might be interested in attending Apple's 
monthly MPW and/or MacApp seminars, you should contact 
Karen Frazier at Apple for data sheets and prices. She can be 
reached at (408) 973-2726. 


7) 
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Mac Hack Forum 


Taking TML Around the 32K Barrier Big Arrays 


It has been a while since I have had a chance to write 
something for my favorate Magazine! MacTutor! A lot of 
Technical Support Questions I get at TML Systems are about the 
32k data limitation that exists on most compilers. I have written 
a work-around that will allow most people to get around this 
problem. 

Most Compilers for the Macintosh have a 32k limitation on 
the sum of all global variables. This is because global variables 
are stored in a area of memory WORD indexed off of A5. This 
is a significant limitation if your program needs large arrays of 
data. There is a workaround, however, to allow any size of array 
to be created. The only size limitation for our array is available 
memory. 

The alternitive way tocreate large arrays is to call New Handle 
to get a handle to a block of memory large enough to hold the 
array. Accessing the individual elements of the new array is done 
by calculating offsets into the block. The Array unit below 
includes routines for Creating and Disposing arrays, and for 
accessing the array elements. 

The unit could be improved by adding support for multi- 
dimentional arrays, dynamic sizing of the array, or even variable 
length data sizes. The speed of the routines could be improved 
substantially by re-coding the unit in 680x0 assembler. Note that 
these routines assume that the lower bound of the array is always 
0. Also, error checking needs to be added to the create array 
routine in case there is not enough memory to create the block. 


( suse se sae sees 3 20 29 2 0:20 m EE EIU (00) 


(8 File: Arrays.Pas в) 
(8 Author: Derry! Loveto. я) 
(8 Description: 1) 


(* This module provides а set of routines to н) 
(8 create & use large arrays 
(alae NL BILE QUON II 


unit Arrays; 
interface 
uses MacIntf ; 


function CreateNewArrayCelemSize, upperBound : 
Handle; 

procedure DisposeArrayCary 
procedure SetElementCary 
: Ptr); 

function GetElementCary 


Longint) : 


: Handle); 


: Hendle; elemNum : Longint; elemPtr 


: Handle; elemNum : Longint) : Ptr; 


implementation 
type 
ArrayHd] = “ArrayPtr; 
ArrayPtr = “ArrayRec; 
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ArrayRec = record 


hiBound : integer; 

cellSize : Longint; 

deteStuff : integer; 

end; 

(tttm tico tato ttt t trt EE HE tan EHE E EU EE EE HE EN I ) 
(8 в) 
(8 function CreateNewArreyCelemSize, lowerBound, в) 
(s upperBound : Longint) : Handle; в) 
tt " 


{ seen ea eee ss ayes san 3 ease m i son 1 sue 18 ae os soon ELE on seen DELLI E208) 


function CreateNewArrayCelemSize, upperBound : Longint) : 


Handle; 
var 
tempHdl : ArrayHdl; 
begin 
tempHdl := ArreyHdlCNewHandleCOrd4CSizeOf CArrayRec2) - 2 


+ (Cupperbound + 1) * elemSize))); 
with tempHdl^^ do 


begin 
hiBound := upperBound; 
cellSize := elemSize; 
end; 
CreateNewArray := Handle( tempHd1); 
end; 


(инниинивиинввииинивниноаининииининииннииниивиннин) 
(в в) 


5 procedure DisposeArray(ary : Handle); | 
" в 
(8 в) 
{2 Sete ea ese en esis mm nmm mm m EHE EE IE UU HET) 
procedure DisposeArreyCaery : Handle); 

begin 

DisposHandleCary); 

end; 
(nnm mm HELDEN ) 
(в в) 
(8 в) 
(8 procedure SetElementCary : Handle; elemNum : ") 
(8 Longint; elemPtr : Ptr); в) 
(8 а) 
tt н) 


(ианининнинининиининяниинянинянининияияняниняниния) 


procedure SetElementCary : Handle; elemNum : Longint; elemPtr 


: Ptr); 

type 
fakeary = packed аггау(1.. 100001 of signedbyte; 
fekeptr = “fakeary; 

var 
cellAddr : fakePtr; 
i : integer; 

begin 


with ArreyHdlCary?^^ do 
if CelemNum > Ø) and CelemNum < hibound) then 
begin 


cellAddr := fekePtrCOrd4CédataStuff) + CelemNum * 
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cellSize)); 
for i := 0 to cellSize - 1 do 
cellAddr^[i] := fekePtrCelemPtr2^[i]; 


end; 
end; 
{ sesees ence ce ease ee snes es ones 10494943 ees DO es S049 104 13 112 18 S2 12 enon L snes IS EE EE) 
(8 procedure GetElement(ary : Handle; elemNum : 8) 
(в  Longint) : Ptr); в) 
(в в) 
ü ") 


(nunnmnunm sues ec snes on es ey sass es sae enka TUER IHREN IUN) 


function GetElementCary : Handle; elemNum : Longint) : Ptr; 


begin 
with ArreyHdlCery2?^^ do 
1f CelemNum > 0) and CelemNum < hibound) then 
GetElement := PointerCOrd4CedataStuff) + CelemNum * 
се11512е)); 


end; 
end. 
(BNNNNNNNNNNNRNNNNNNNNNNNNNNNNNNNNNHHNNEREENNNNHHN ) 
8 а) 
р This progrem tests the Array Peckage a) 
a п 
(8 в) 


(иинниинининвоиннниииннипинииинининнииннинониниин) 


program AryTestCinput, output); 
uses Macintf, Arrays; 


type 
BigPtr = “BigRec; 
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BigRec = record 


r : real; 
r2 : real; 
other : аггеџ[1. .201 of Longint; 
end; 
ver 
myArray : handle; 
i : longint; 
Big : BigRec; 
x : integer; 
StackMark : integer; 
begin 
SetAppILimit(Pointer(Ord4(@StackMark) - 0г94( 1600022); (16k 
steck) 
MaxApp Zone; 


myArray := CreateNewArray(Size0f (BigRec), 2000); 


writelnC^Total Size of Record = ‘,SizeOf (BigRec)); 
writeln(€ ‘Total Size of the array = 
' GetHandleSizeCmyArray)); 
writeln; 
writelnC'press mouse to start’); 
repeat until button; 


for i := Ø to 2000 do 
begin 


Big.r := i / 1.0; 
SetElement(myArray, i, @Big); 
writelIn(BigPtr(GetE lement(myArray, 1227.г:7:2); 


end; 


DisposeArray(myArray); 


end. 
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Pascal Procedures 
Blasting Holes in Windows 


How To Bulld A Laser Cannon: 
A Home 5.011. Project 


Bit O' History 


I wish I came up with the idea to blast holes in windows, but 
Ididn't. The credit goes to Andrew Donoho and Darin Adler. 
Andrew is the author of MacSpin, a 3-d data analysis tool. 
MacSpin allows a user to rotate a “cloud” of data points around 
any of three axes in real time. Because of its highly interactive 
nature, Andrew likes to refer to itas a thinking man's video game. 
Heand Darin gottogether and decided that MacSpin was missing 
a feature essential to successful video games: laser cannons. 
They envisioned a user holding down command-shift-option- 
capsLock and being rewarded by laser turrents appearing in the 
corners of the data window. Add in some crosshairs with range 
and elevation readouts, and the user could blast away! They 
figured laser cannons would be especially useful in MacSpin, 
where unwanted data points could be annihilated, thus saving a 
pet theory from bothersome reality. 

Andrew continued to joke about actually implementing laser 
cannons. That's how my partner, Scott Boyd, heard about it. 
Scott was working closely with Andrew on enhancements for 
MacSpin when the subject of laser cannons came up. Scott 
knows a good idea when he hears one (most of the time), so he 
immediately urged Andrew to stop joking and do it. More 
pressing concerns kept them both busy for a while, but the idea 
wouldn’t die. 


Laser Cannons Are Born 


I learned about laser cannons in a phone conversation with 
Scott. I know a good idea when I hear one, too (I hope...). They 
were busy. I wasn’t. By the time Scott came home from Austin 
a couple of days later, I had the first incarnation of Blast finished. 
It was an application that brought up a window, and made holes 
wherever the cursor was when the mouse button was pressed. 
The holes were plain and round, and it ran silently. The holes 
weren’t even centered under the cursor. But gridlines drawn in 
the window showed that the holes were “not there.” Thatis, holes 
had been cut out of the structure of the window. Wow... laser 
cannons. 


“Useless Interface” Concerns 
Scott and I talked about what the holes should look like. After 
some discussion, he drew some sample holes in MacDraw. After 
a while, he had something we both liked. I took the coordinates 
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Fig. 1 Blasting holes in Full Paint's windows! (note how 
the cursor changes over a hole to the arrow, proof that it Is 
not in the window!) 


of the vertices around the hole, and put in some code to make a 
region (instead of just using circles). While I was at it, I started 
centering the hole under the cursor. So far, so good. 

Sound came next. Poking holes in things isn't very much fun 
if you don't get some sort of aural feedback. We discussed all 
sorts of options, from simple beeps to elaborate crashing noises. 
I chose the easy route and used the Sound Driver to make some 
square-wave sound. 

Making sound on the Mac is pretty easy if you're willing to 
settle for single voice tones. Each tone is described by a trio of 
values known as a “triplet.” These numbers describe the pitch, 
volume, and duration of the tones you want to play. I decided to 
use twenty triplets. The last triplet has zero for all three values, 
to tell the Sound Driver to stop making noise. For the other 
nineteen, I chose a starting value, then decreased the pitch and 
volume of each succeeding tone. This gives the impression of 
something moving into the distance, like a train's whistle as it 
heads away from you. 


Now We're Getting Somewhere 
Blast didn't change much after I added sound. The biggest 


change was in “packaging.” I wanted Blast to be available from 
anywhere, so I decided to make it intoan FKEY. Butasan FKEY, 
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Blast had to stop counting on having access to global variables 
and resources. QuickDraw globals such as screenBits and 
thePort may not be available while an FKEY is running. And, 
counting on certain resources being installed along with the 
FKEY is a sure way to see everybody's favorite bomb box. So, 
Blast became a procedure in a UNIT. The procedure has 
everything in it Blast needs to do its dirty work. [The version 
presented here is compatible with both MPW Pascal and LS 
Pascal. The unit can be either installed as an FKEY or you can 
call the unit from a program. In the code listing, a USES 
statement is presented for both MPW and LS Pascal. Since LS 
Pascal requires code resources to have a MAIN entry point, a 
procedure with the name MAIN was added to the unit, which calls 
Blastlt. This MAIN can be removed for MPW. -Ed] 


Gory Detalls 


The first thing I do in Blast is allocate a non-relocatable block 
for the sound buffer, and fill it with triplets. Then I go about 
putting up the crosshair cursor. I want to be polite and give the 
user their original cursor back when Blast is done, so I have to 
know what it is. But there isn't a call to get the current cursor. 
Apple seems to feel that the cursor should be “write-only.” [have 
to dip into low memory and suck the cursor out the hard way. I 
suppose this is “against the rules,” but I refuse to sit back and 
hope the application running is smart enough to update its cursor 
when Blast is through. I set up the crosshair cursor and do a 
SetCursor call. Remember what I said about no resources? The 
crosshair cursor is hard-coded into Blast and the way I set it up 
is by using StuffHex to load up a cursor variable. It looks kind 
of gnarly, but it helps make Blast self-contained. 

Once the cursor is up (so the user gets some immediate 
feedback), I pre-fabricate the hole. To do this I open aregion, and 
draw the outline of the hole. OpenRegion hides the QuickDraw 
pen, so the user doesn’t get to see any drawing happen. Then I 
close the region and move it to the origin, (0,0). This makes the 
size calculations simple, since the top and left coordinates are 
both zero. I want to know how big the hole is in order to “add in" 
a round part (sort of like a bullet hole). I make another region 
shaped like acircle, and use UnionRgn to add it to the jagged part. 
After the composite hole is prepared, Blast is almost ready to go. 
First, though, I set the current port to be the window manager port 
(the whole screen). This is so the coordinates of the holes line up 
with the windows' regions out on the desktop. 


The Heart Of The Matter 


The main loop is pretty straightforward. Wait for a mouse 
click. If the click is in the content region of any window, go to 
work. Initiate some asynchrounous sound by calling StartSound. 
Move the hole to center it under the mouse. Subtract the hole (via 
DiffRgn) from the content region and structure region of the 
window. Presto! Laser cannons. After blasting a window, all the 
windows underneath the blasted one need to be notified that they 
have newly visible areas. I use the low-level Window Manager 
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call CalcVisBehind to do this. It recalculates the visible regions 
of all windows under the given window that intersect a certain 
region (the hole region). PaintBehind is called to paint newly 
visible areas, including the desktop. The new system paints 
windows with their background patterns, instead of always 
painting white like the old system. 

If the user clicks anywhere but a content region, Blast exits. 
Itthrows away the hole region and the sound buffer, then restores 
the cursor and the old port. However, the windows retain their 
missing holes so you can drag a window around and see the 
windows behind through the holes. You can even scroll the 
window and watch the contents move around the hole! Only 
when you cause the window manager to reconstruct the window 
such as growing or zooming the window, do the holes go away. 
See figure 1. 


FKEY, What's An FKEY? 


Now for a few words about FKEYs. The Mac deals with 
FKEYs behind the scenes by intercepting key-down events when 
GetNextEventiscalled. If an FKEY resource with the ID number 
of the key that was hit is found, the system loads it in and executes 
it. When the FKEY is done, it passes control back to the system, 
which then flushes the event and pretends it never happened. 

Blast can be called up from within any program that calls 
GetNextEvent. As a matter of fact, Blast can be called recur- 
sively from within itself, since it calls GetNextEvent. This 
presents no real problem, since Blast carries its own local 
variables around. I guess the only limit is how much stack space 
you have, since each activation uses up several bytes of the stack. 


The Recipe for MPW 


Making “non-applications” is relatively simple in MPW, as 
long as you pay attention to a few technical details. I made Blast 
part of a Pascal UNIT so the compiler wouldn't try to create a 
main entry point. If it was a PROGRAM, the compiler would 
stick in a whole bunch of global variable initialization code and 
try to identify an entry point. FKEYs don’t have global variables 
(traditionally accessed relative to register A5), so any extra code 
provided by the compiler is decidedly unwelcome! [Note that for 
LS Pascal, a main entry point is required! But the DA PasLib file 
is used instead of the regular PasLib so that none of the initiali- 
zation for a program is done. By clicking on the code resource 
option, everything gets built correctlyfor you. See figures 2,3 and 
4. -Ed] 

Once the compiler is through chewing on it, the resulting 
object file (the .p.o file) is passed through the linker. The linker 
puts in any glue code needed by functions called by Blast. Glue 
code is most commonly used to interface between Pascal, with its 
stack-based calling convention, and some parts of the Mac ROM 
that are register-based. The glue takes parameters off the stack 
and puts them in registers before calling the ROM routines. Then 
it takes any result from a register and puts it on the stack before 
returning to the main program. Another kind of glue is used for 
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range checking by the compiler. The compiler calls glue routines 
to check the length of strings and such when range checking is 
turned on. 

After the glue is taken care of, the linker expects to be told 
where the entry point is. The -m option on the linker let me point 
to the proper procedure in the Blast UNIT. The linker makes sure 
that the very first instruction in the resulting program jumps to the 
entry point. An FKEY resource is just like a CODE resource 
withoutany jump table information. With the -rtoptionI told the 
linker to create FKEY resources instead of CODE resources (the 
default). I also told the linker to rename the main code segment 
from Main to BlastKey with the -sn option. This provides a 
reminder when viewing the resource in ResEdit. I use ResEdit to 
install the FKEY in the system file. FKEY Installer and FKEY 
Manager should work just as well. 


Adding Blast to Hypercard 


Everyone I've talked to about WildCard (now known as 
HyperCard, but I think that name is really dumb) is impressed by 
it. One of the neatest features is the ability to compile your own 
commands and add them to WildCard. I recently got ahold of 
some sketchy documentation about these XCMD resources and 
decided to make Blast into a WildCard command. The only 
difference between an FKEY and a XCMD is that XCMDs take 
a single argument on the stack. WildCard passes a pointer to a 
block full of information to the XCMD upon activation. Inside 
that block of information are all sorts of goodies, like handles to 
command-line arguments, a place for a result code, and several 
fields to allow the XCMD to communicate directly with Wild- 
Card. I wasn't really interested in all that parameter stuff (yet!), 
so I ignored it for the moment. АП I had to do to make Blast 
WildCard compatible was to add a formal parameter to the 
procedure in the UNIT. I just changed its declaration from 
PROCEDURE BlastIt; toPROCEDURE BlastItC aParam : Ptr );. 
Then I changed the link statement to produce XCMD resources 
instead of FKEY resources. Voilá, a brand new WildCard 
command. By the way, the name of the resource is important 
here, because that's how WildCard knows which XCMD is for 
which command. 


Up On The Soap Box 


Idon'tknow who made up some of the “rules,” but they're not 
going to be too happy with Blast. Imanaged to break quite a few 
of them along the way. The first infraction is sneaking into low 
memory to get the current cursor. Using any low memory 
globals is frowned upon. Look at all the trouble Think got into 
when they used BasicGlobs. For those that don't know, Ba- 
sicGlobs was to be used by MacBasic, which never made it to 
market. Think's Lightspeed C generated code that used it for a 
scratch area. Apple started to use itin System 4.1, blowing away 
awhole bunch of programs. Think has corrected the problem, but 
they blame Apple for changing their minds about using Ba- 
sicGlobs. The way I see it, anybody who uses low memory areas 
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without express written approval from Apple deserves what they 
get. Apple has stated many times that low memory is off limits. 
In fact, the area we know as low memory is going to disappear in 
future architectures. But sinceI'm only reading (and not writing) 
low memory, I'll just get trash if they ever move the cursor 
storage area. 

The next infraction is a biggy. Blast directly modifies the 
fields of a windowRecord, namely the strucRgn and contRgn. 
Apple is really touchy about windowRecords, especially since 
the invention of Juggler (now known as MultiFinder, but I think 
that name is really dumb, too). Juggler does all sorts of neat 
things with windows and window lists to manage multiple 
applications. Blast isn't directly affected by this, but Juggler 
proves that Apple is serious about changing window handling 
without notice. When Apple gives us windowing hardware, 
programs like Blast will be next to impossible (but I'm gonna try 
it anyway! ). 

The next one is more a matter of style, but could cause 
problems. I just assume that Blast will have plenty of memory to 
make the sound buffer and the hole regions. I wouldn't recom- 
mend using Blast when you've got a bunch of unsaved data and 
can't afford to crash with an out of memory error. 


Credits, etc... 


Thanks to Andrew and Darin for having the idea, and to Scott 
for planting the seed in my head. Speaking of seeds, TECHNOS- 
TUD (a.k.a. Steve Knouse) helped out by showing Blast to 
anyone he could drag over to a Macintosh for two minutes. Steve 
is sort of like a reverse Johnny Appleseed. He goes around 
sowing MacHax™ programs on Apples everywhere. Thanks for 
all your support, Steve. And thanks to Dave Smith, who put me 
on a panel at the Boston MacWorld Expo. That's where Blast 
made its public debut. To all the attendees of that panel, here is 
Source code, only two months late. 

І can be reached at any of the following: 


3420D Sandra St. 
Bryan, TX 77801 
(409) 846-4102 


AppleLink: D0635 
MCIMail: Greg Marriott 
BITNet: max@tamlsr 


Blast project 


Options File (by build order) Size 
ОА PasLib 8072 


MacTraps 6006 
ROMSSLib 980 
duci ROMSS 0 


[MR] BlastStuff 1438 


(б) 
[р] 


Fig. 2 LS Pascal Project Definition 
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UNIT BlestStuff ; 
(MPW апа LS Pesca! Version) 
INTERFACE 


( For MPW, use the following USES statement) 
USES ($LOAD fkeyblast .dump) 
MemTypes, QuickDrew, OSIntf, ToolIntf; 


( For LS Pascal, use the following USES statement) 
USES 
ROM85; 


PROCEDURE BlestIt; 
PROCEDURE Main; (not needed for MPW) 


IMPLEMENTATION 
PROCEDURE BlestIt; 
CONST 


buffSize = 122; 
( sound tekes 2, 20 triplets = 120 bytes ) 
VAR 
holeRgn, circleRgn : RgnHandle; 
theEvent : EventRecord; 
stopIt : Boolean; 
whichWindow : WindowPtr; 
thisWindow : WindowPeek; 
i, dur, cnt, ninSize:Integer; 
pictWidth, thePart : Integer; 
blastPict : Pichandle; 
enotherRect, circleRect, tempRect : Rect; 
mouseSpot, holeSize, middlePoint : Point; 
wPort, oldPort, tempPort : GrefPtr; 
DeskPattern : “Pattern; 
crossHeirs, oldCursor : Cursor; 
TheCurs : “Cursor; 
squereWevePtr : SWSynthPtr; 
emp : integer; 


BEGIN 


( let’s set up sounds... ) 

SquareWevePtr := SWSynthPtr(NewPtr(buffSize2)2; 
squareWavePtr^.mode := swMode; ( squarewave mode ) 
cnt := 400; 

emp := 150; 


( 19 triplets, with decreasing pitch and volume ) 
FOR i := 0 TO 18 DO 
WITH squareWevePtr^ .triplets(i] DO 
BE 


count := cnt; 

amplitude := amp; 

duration := 1; 

cnt := cnt + 60; 

emp := emp - 8; 
END; 


WITH squereWevePtr^ .triplets(19] 00 
BEGIN 


count := 0; ( quit ) 

enplitude := 0; ( making ) 

duration := 0; ( sounds ) 
END; 


( let’s put up our cursor, saving the old one first...) 
( there is no ‘GetCursor’ call to complement ) 
( ‘SetCursor’, } 
( so we have to dip into low memory and steal it } 
TheCurs := pointer($844); 
oldCursor := TheCurs’; 
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€3 blast demo stuff 


t Blast Code 
D Blast project 
(Y BlaetStuff 


(| =œ HP40-6 


Save 'Blast project' as 


© Application © Desk Accessory 
© Library О Driver 
© Compressed Project © сабе Resource 


Fig. 3 Creating a Code Resource in LS Pascal 


Pascal Blast.p 

Link -rt FKEY=8 -m BLASTIT -t FKEY -c RSED д 
-sn “Main=BlastKey” д 
Blest.p.o à 


* (Libreries)^Interfece.o à 
-0 Blast .fkey 


Listing 2: MPW Make file for Blast 


FKEY ID=3 


Fig. 4 Installing an FKEY in the System File 
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circleRgn := NewRgn; 


( we need to put data into our cursor variable so we) OpenRgn; 

( can do а 'SetCursor^ call. stuffing the data ) FrameOval(circleRect); 

( directly into low memory doesn’t work, because the } CloseRgn(circleRgn); 

( cursor on the screen wouldn't change until mouse ) ( add the circle to the hole ) 

( wes moved ) UnionRgnCholeRgn, circleRgn, holeRgn); 

Stuf fHex(ptrC@crossHairs), '/7107408140810000' ); ( we don’t need this any more... ) 
StuffHexCptrClongintCécrossHairs) + 8), DisposeRgn(circleRgn); 

'049002A04 1С 17777); ( make the window manager port the current port ) 
Stuf fHex(ptrClongintC@crossHairs) + 16), GetPortColdPort); 

^41C 1924004900900 ' ); GetWMgrPor tCwPort); 
StuffHexCptrClongintCécrossHairs) + 24), SetPort(wPort); 

“408 1408 17 170000” ); 

Stuf fHex(ptrClongint(@crossHairs) + 32), (ок, setup’s 811 finished... here’s the “main loop” ) 

01002082 10840808 ' ); StopIt := FALSE; 

Stuf fHexCptrClongintCécrossHairs) + 40), REPEAT 

^giFOOTFOATF 177Е7'); ( accept only mouseDown events ) 

Stuf fHex(ptrClongintC@crossHairs) + 48), IF GetNextEvent(mDownMask, theEvent) THEN 

^4TF 107FØ07F 00808 ' ); BEGIN 
Stuf fHexCptrClongint(@crossHairs) + 56), ( figure out where they clicked } 

‹ 108420820 100000”); thePart := FindWindowCtheEvent where, whichWindow); 
Stuf fHex(ptrClongintC@crossHairs) + 64), '00070008'); ( respond only if click on content area of window ) 
SetCursor (crossHairs); IF (thePart = inContent) THEN 

BEGIN 

( make the jaggy hole ) ( Make some asynchrounous noise ) 
holeRgn := NewRgn; Star tSound(Ptr(squareWavePtr), buffSize, NIL); 
OpenRgn; mouseSpot := theEvent where; 
MoveTo(250, 180); ( position hole centered over the mouse spot ) 
LineTo(268, 226); WITH holeRgn^^.rgnBBox DO 
LineTo(230, 252); OffsetRgnCholeRgn, -left, -іор); 
LineTo(260, 242); OffsetRgnCholeRgn, mouseSpot.h - holeSize.h DIV 2, 
LineTo(232, 278); mouseSpot.v - holeSize.v DIV 2); 
LineToC270, 242); ThisWindow := WindowPeek(whichWindow); 
LineTo(286, 304); ( blast а hole in the structure region ) 

( basic hole design by Scott Boyd ) DiffRgnCThisWindow^ .contRgn, holeRgn, 
LineToC278, 234); ThisWindow^ .contRgn); 
LineToC306, 242); ( blast а hole in the content region ) 
LineTo(278, 244); DiffRgnCThisWindow^.strucRgn, holeRgn, 
LineTo(314, 196); ThisWindow* .strucRgn); 
LineToC270, 216); 
LineTo(250, 180); ( calculate and paint new visible regions ) 
CloseRgnCholeRgn); CalcVisBehind(WindowPeekCwhichWindow2, holeRgn); 


PaintBehind(windowPeekCwhichWindow), holeRgn); 
( “home” the region, prepare to add circle о) 


( the middle of the hole ) (since ‘PaintBehind’ messes with the port.. ) 
WITH holeRgn** .rgnBBox 00 SetPor t(wPort); 
OffsetRgnCholeRgn, -left, -top); END (IF € thePert = inContent >... ) 
( calculate size ofhole and where the middle is ) ELSE 
WITH holeRgn^^.rgnBBox DO ( didn’t click in а window? ) 
BEGIN StopIt := TRUE; 
holeSize.h := right - left; END; (IF GetNextEvent...) 
holeSize.v := bottom - top; UNTIL stopIt; 
niddlePoint.h := (right - left) DIV 2; ( clean up the hole ) 
middlePoint.v := (bottom - top) DIV 2; DisposeRgnCholeRgn); 
END; ( fix the port 
( figure out what size to meke the circle ) SetPort(oldPort); 
IF holeSize.h > holeSize.v THEN ( put the old cursor back ) 
ninSize := holeSize.h SetCursorColdCursor?); 
ELSE ( get rid of the sound buffer ) 
minSize := holeSize.v; DisposPtr(CPtr(CsquereWevePtr)); 


END; (BlestIt) 
( ие^11 make the circle 408 of the small dimension;) 


( ninSize will be the redius of the circle ) PROCEDURE Main; (Not needed for MPW) 
minSize := minSize DIV 5; BEGIN 
WITH middlePoint DO BlastIt; 
SetRect(circleRect, h - minSize, v - minSize, h + END; 


minSize, v + minSize); 
END. 


( make the circle } 
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Macintosh П 


CDEV Control Panel Files Revisited 


ApplFont - Control Panel Files 


This months article will discuss the most obvious, and per- 
haps important, feature of the new System/Finder (not the bulg- 
ing trash can or the spinning watch hands), the expandable 
Control Panel. 

The new Control Panel is no longer a fixed Desk Accessory 
with only a single appearance/function. Similar to the Chooser, 
the new Control Panel now refers to special files in the System 
Folder. Each of these special Control Panel Files or cdev files 
appears а$ ап Iconon the left side of the Control Panel. When one 
is selected, the corresponding cdev file tells the Control Panel 
how to draw therightside of the Control Panel. The cdev file also 
has code inside it that that tells the Control Panel what to do when 
a User selects something on the left side of the Control Panel. 
Now the User can pick and chose his cdev files, like he does his 
Desk Accessories, Fonts or FKEYs. Each new cdev gives the 
User a new way to change and “Control” his Macintosh. 

While Apple has released some cdev files (General, Key- 
board, Mouse, Monitor, Sound, Startup Device), a number of 
other ones have appeared. This article will explain how to create 
such a cdev file. 

The new Control Panel and cdev files are of special impor- 
tance to Mac // users. While the Chooser is the standard way to 
contact peripherals (like Printers or File Servers), the Control 
Panel is the method used to control the internals of the Machine, 
including expansion cards. A cdev can be created that will only 
function on a specific machine (one that has Color Quickdraw) 
or even only one that has a particular expansion card installed. 


cdev File Format 


A Control Panel File contains several set of resources. Each 
group is used for a different purpose. A cdev files has no 
information in it's data fork. Besides the resources, a cdev file 
has the File Signature of 'cdev' and a specific File Creator 
(matching the BNDL resource, see below). It's bundle and init 
bits must be set. 

The first resource that is checked when the Control Panel is 
open is the *mach' resource of ID -4064. This resource tells the 
Control Panel if this cdev can be used on this machine. The 
resource contains 2 word values, the SoftMask followed by the 
Hardmask. The Softmask is compared to the global variable 
ROMSS to check for software features, while the HardMask is 
compared to HwCgfFlg to determine the Hardware features. The 
cdev will appear in the Control Panel if every bit that is O in the 
Softmask is 0 in ROMSS and every bit that is 1 in the Hardmask 
is 1 in HwCgfFlg. For example, the Softmask of $FFFF and 
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Fig. 1 Selecting our CDEV in the Control Panel 
Hardmaks of $0000 would go with a cdev that would appear on 
any machine. Softmask of $3FFF and Hardmaks of $0000 would 
go with a cdev that would appear on a Mac // only. Finally there 
is the special case of a Softmask of $0000 and a Hardmaks of 
$FFFF. This is for a cdev that needs to check for more informa- 
tion than is stored in ROM85 and HwCgfFlg. In that case, the 
Control Panel calls the ‘cdev’ resource code to ask if the machine 
is correct (more about this below). This case would be used for 
a cdev that needs to have a certain expansion card be installed. 

Seconda cdev file must have its own icon. Not only will this 
Icon appear in the Finder, the Icon appears on the left side of the 
Control Panel. The Icon must be stored as a ICN# resource of ID 
number -4064. The associating resources BNDL and FREF (ie. 
ones that make the Finder know ICN# -4064 is to be used) must 
be set correctly and have the ID number -4064. The BNDL 
resource will have the File Creator that the cdev file must have. 
Finally there must bea ownerresource of the same matching type 
as the File Creator (ID O) in the file. Just remember that the ICN#, 
BNDL and FREF must be ID -4064 (normally they can be 
anything). 

Next the cdev file must contain information on how the right 
side of the Control Panel will be displayed. When an Icon is 
pressed on the left side of the Control Panel, the Control Panel 
check the matching cdev file. It is looking for a resource of type 
DITL, ID -4064. It adds this DITL to the DITL it is using to 
display the entire Control Panel (left and right side). Thus all the 
various Buttons, Icons and Text seen on the Panel are stored in 
various DITL files. If a certain cdev wants to display a unusual 
feature, it’s DITL resource may have a number of userltems. 
This is how the General cdev has such an unusual appearance. 
The Control Panel also checks a ‘nrct’ resource of ID -4064 when 
it draws itself. A *nrct' resource contains a number of rectangles 
on the right side of the Control Panel. The exact format of the 


O The Essential MacTutor, Vol. 3 


resource is a word value containing the number of rectangles in 
the resource, followed by the 4 word values (top, left, bottom, 
right) per rectangle (if any). The latest version of ResEdit has a 
TMPL for the correct format of *nrct'. On the right side of the 
Control Panel, each rectangle is filled in with white and framed 
before the DITL is drawn. Any area not in a rectangle is filled in 
with gray. The rectangles are set to overlap so that the lines 
between the boxes are thicker than 1 pixel. Examine the Mouse 
and Keyboard cdev files for examples of this. 

Lastly the cdev file must have a resource of type ‘cdev’, ID - 
4064. This resource is a code resource similar to a FKEY or a 
Window Proc. This code takes care of the event handling for the 
right side of the Control Panel. As mention above, it also takes 
care of special checks to see if this cdev should appear on this 
machine at all. The exact format of the ‘cdev’ resource is 
explained below. 

The cdev file can contain additional resources that the ‘cdev’ 
code can use. These resources must be in the range of ID -4048 
to -4033. Whenever the cdev' code resource is called, the cdev 
file resource fork will be open. Thus all the additional resources 
can be used. They can even be changed, and this changed value 
can be written back to the resource file by changing the value of 
the handle, calling ChangedResource, then calling WriteRe- 
Source. As explained below, this is a convenient way to save 
information between system resets. 


cdev Call 


An 'cdev' resource is a code resource similar to a FKEY or 
Window Proc. Whenevercdev iscalled, the current Grafport will 
always be set to the Grafport holding the right side of the Control 
Panel. The entry point of the resource has this format: 


FUNCTION cdev( message, item, numItems, CPenelID: INTEGER; 
theEvenT :EventRecord; 
cdevStorage: Handle; 
CPDialog: DialogPtr): Handle; 


Remember that the Control Panel draws most of the right side 
of the desk accessory by adding the DITL in the cdev file to the 
Control Panels own DITL. Thus the first item in the cdev files 
DITL may be the 7th item in the Control Panel DITL (after the 
cdev DITL is added) if were 6 items to begin with. 

The CPDialog parameter is the DialogPtr that contains the 
Control Panels DITL. CPanelID is the base resource ID of the 
Control Panel DialogPtr. The parameter numItems is the actual 
number of items in the Control Panel DITL before the cdev DITL 
was added. The parameter theEvenT is the EventRecord of some 
action that cdev has to take care of, while item is the number of 
some item in the DITL that has been just been pressed. The 
cdevStorage parameter normally contains the value that was last 
returned by the last cdev call. This parameter сап be used to store 
internal data or pass error messages. 

The key parameter to the cdev function is message. It value 
tells the function exactly what is should do for this call. It can be 
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Fig. 2 Our CDEV In operation 


passed the following values: 
CONTS  initDev = Ø; 
hitDev = 1; 
closeDev = 2; 
nulDev = 3; 
updateDev = 4; 
act ivDev = 5; 
deActivDev = 6; 
keyEvtDev = 7; 
macDev = 8; 


The messages updateDev, activDev, deActivDev and 
keyEvtDev are fairly simple. Each of these messages handles a 
praticular type of event passed by the theEvenT parameter. In 
many case, such a call would do nothing since the Control Panel 
is doing most of their work. The nulDev message is sent to the 
cdev on every desk accessory run event. An clock cdev could use 
this message to change the time of the clock. 

The initDev and closeDev calls are called when the cdev is 
opened or closed. The calls with these messages should create or 
delete any private storage. The initDev call may also make any 
changes to the cdev portion of the Control Panel (ex. hiliting the 
buttons, checking boxes, setting text, setting userltems). When 
InitDev is first passed, cdevStorage does not contain a real 
handle. It actually contains a longint value of 3. If the cdev does 
not want internal data, the cdev can return the cdevStorage handle 
and everything will work. If the cdev does want internal storage, 
the cdev should create the handle, initialize the data, and return 
it as the function’s results. The next call to cdev will have 
cdevStorage contain this handle. As long as all future call pass 
the cdevStorage handle as the function’s results, the handle can 
be used as storage safely. When а closeDev message is sent, the 
cdev must release the storage handle (if there is one). Remember 
that this internal data structure is strictly alive while the cdev is 
being displayed in the Control Panel. If another cdev is picked 
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or the Control Panel is closed, the closeDev message is sent and 
the cdev is closed. 

If at anytime, the cdevStorage parameter contains the values 
-1,0 or 1, the cdev call must do nothing but return the parameter 
as the function result. These values are error codes and indicate 
that the Control Panel is having some problem. If the cdev itself 
ever has an error, it can return these values. The Control Panel 
then will gray out the right side of the Control Panel. Error 0 
indicates a memory error, and the Control Panel will display a 
message to that effect. Error 1 indicates a resource error (re- 
source not found), and will display a message to that effect. Error 
-1 indicates some cdev specific error. In that case, the cdev 
should briefly put up it'S own message. 

The hitDev call is fairly obvious. The user has just pressed an 
item. The item number is in the parameter Item. Remember that 
this number is not based on the cdev DITL, but on the DITL 
created by the Control Panel by adding DITLs. The cdev call 
usually does something at this point to change the operation of the 
Macintosh. Thecall may also wantto change the DITL toexplain 
the change (ex. check a new box and uncheck the old one). 

The macDev is only passed when the ‘mach’ resource of the 
cdev file contains $0000 and $FFFF. Then the cdev must decide 
if it should be shown on this machine. If so, the function should 
return 1. If not, it should return 0. These 0 and 1 values have no 
relationship to the 0 and 1 error codes describe above. This call 
is done before the cdev is formally opened. 


Init Resource 


The General and the ApplFont files allows the user to set the 
Parameter RAM of the Macintosh. The Parameter RAM settings 
will stay effect until changed. Even when the Mac is turned off, 
the Parameter RAM stays active, thus saving the values between 
sessions. However, there are some effects that can only go into 
effect after certain code is executed. Such cdev files can use a 
INIT resource to do want they want. Ап INIT resource is a code 
resource like FKEY or cdev that is executed at startup by the 
system. It is a procedure call with no parameters. Normally an 
INIT resource must be in the System file. However one of the 
INIT resources that is in the System file checks other files in the 
System Folder for INIT resources. Files of various Types 
(including ‘INIT’ type and, as of the latest System, 'cdev' type) 
are checked for any resources of type INIT. If one is found, it is 
executed. This is an extremely powerful feature. 

The best way to explain this idea is to give an example. Say 
someone wants to create a cdev that turns on or off some specific 
function. The cdev file for such an example would consist of 
several parts. First there would be the normal cdev file format 
containing the DITL, ICN#, cdev and other resource. There 
would also be a special resource (name and type is unimportant) 
that would contain a single boolean variable. Inside the cdev 
resource is the code that turns on or off the specific function. 
Everytime the user would press the correct on or off button in the 
Control Panel, the cdev code would turn the function on or off. 
It would also store the latest on or off value inside the special 
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boolean resource (by changing the value of the handle, calling 
ChangedResource, then calling WriteResource). Remember 
that the cdev file resource fork is always open whenever the cdev 
code resource is itself being called. 

So far the example would work until Mac power is turned off. 
When the machine is turned back on, the user may want the 
special function to be in effect. This would not occur until the 
cdev file is selected in the Control Panel. Then the cdev code 
would have a chance to see if the special feature should be turned 
on. To solve this problem, the INIT resource comes to the rescue. 
On system startup, the resource would be executed. It would 
check the special boolean resource (INITS, like cdevs, always are 
called with the resource fork of the file containing them open). If 
the boolean value is on (from the last time someone set it with the 
Control Panel), the INIT resource would turn on the special 
function. Thus the entire cdev file would always make sure the 
special blanking is set the way the user wants it. 

Consider the example of an auto-screen blanking cdev. Such 
a function makes the screen go dark if no one has used the 
Macintosh after some set time period so that the Macintosh 
screen does not get a burned image. An auto-screen blanking 
function usually works by inserting a checking routine (check 
how long it's been since someone has use the Mac) in the system 
heap (where it would not be destroyed when the applications are 
switched). To turn the routine on or off, the memory location of 
the routine needs to be installed into or removed from one of the 
various Macintosh timers. Thus the memory location must be 
saved between various times the Control Panel is accessed. To 
do this another special resource would probably be used that 
contains the longint memory address. The INIT resource would 
initially install the blanking routine and save the memory loca- 
tion into this special resource. The INIT would may or may not 
turn on the install the routine in a time queue depending on the last 
setting of the Control Panel. The later calls to the cdev would use 
the memory location to turn the blanking on or off. 


The Code 


ApplFont is a sample cdev file that allows the users to set the 
Application Font value. This value is one of the few Parameter 
RAM settings that is not changed by the General, Mouse or 
Keyboard cdev Files. Since itis a Parameter RAM that is being 
changed, no INIT resource is needed. 

The Application Font is a special reference Font. It is nota 
true Font like the other Font ID numbers. Normally when a 
program sets the txFont field of a Quickdraw Grafport to some 
number (using the TextFont procedure), all Text drawing would 
be done in the Font that has the matching ID number. However 
when the txFont field is setto one (1), the Font used is the one that 
matches the Application Font ID number. Many programs and 
Desk Accessories draw using the Application Font, thus allow- 
ing the user to select the Font. 

The actual value of the Application Font portion of the 
Parameter RAM (font field of the SysParmType data structure) 
must be the Application Font number minus 1. Since Quickdraw 
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only refers to the Parameter RAM at system boot to retrieve the 
Application Font number, changing this number will not effect 
the system until the next reboot. While it is not dangerous to 
change the number (using the GetS ysPPtr and WriteParam calls), 
asimple rule needs to be observed. Never change the Application 
Font to a Font that is not installed on the System, or the System 
will not function. 

The original ApplFont file was created using ResEdit while 
the cdev resource was created using Lightspeed Pascal. The 
Resource file (MPW format) enclosed here could have just as 
easily created all the resources save the cdev resource. It is still 
easiest to use ResEdit to paste the compiled cdev resource into the 
finished cdev file. Use ResEdit to change the File Signature and 
Creator (in this case, ‘cdev’ and ‘apft’). Do not forget to set the 
bundle and init bit so the Icon will be displayed. 


( AppFont - Application Font Control ) 
( by Steve Sheets 
( Control Panel Proc to change Application Font ) 


UNIT AFunit; 
INTERFACE 


FUNCTION Main (message, item, numitems, 
CPanel : integer; 
theEvent : EventRecord; 
cdevStorage : longint; 
CPDialog : DialogPtr) : longint; 


IMPLEMENTATION 


( Given the DialogPtr to the Control Panel, and the number of 
items in the original Control Panel DITL and the Number of the 
Font Button to be selected, selects that Font Button and 
unselects а11 the other Buttons. ) 


PROCEDURE DoHit (N, X : integer; 
CP : DialogPtr); 
VAR 


count : integer; 
тут : integer; 
myH : handle; 
myR : rect; 
BEGIN 
FOR count 
BEGIN 
GetDItemCCP, count, myT, myH, MyR); 
IF count = N THEN 
СООО шие ын 
$ 


=Х+1Т0Х+ 16 DO 


SetCtlValueCControlhandle(myH), 0); 
END; 
END; 


( First finds the current Application Font ID number, converts 
that ID number into corresponding Font Button number and 
returns thet number. ) 


FUNCTION CurNum : 
VAR 


SP : SysPPtr; 

V : integer; 
BEGIN 

SP := GetSysPPtr; 

ү := SP^.Font + 1; 


integer; 
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CASE V OF 
0: 


CurNum := 1; 

2, 3, 4, 5, 6, 7, 8, 9: 
CurNum := V; 

11, 12: 


CurNum := V - 1; 
20, 21, 22, 23, 24 : 


CurNum := V - 8; 
OTHERWISE 
CurNum := 0; 
END; 
END; 


( Given the Font Button number, converts it into the Applica- 
tion Font ID number, then sets the current Application Font to 
thet number. ) 


PROCEDURE SetNum (N : integer); 
VAR 

SP : SysPPtr; 

E : OSErr; 

V : integer; 
BEGIN 

CASE N OF 

Ls 


1 
V := N + 8; 
OTHERWISE 
V := Geneva; 


END; 

SP := GetSysPPtr; 

SP^.Font : V - 1; 

E := WritePerenm; 
END; 


( For all the Font Buttons, checks to see if that Font is 
installed in the system. If it is not installed, unhilites the 
corresponding button so it cen not be selected. ) 


PROCEDURE ZepFonts CCP : DialogPtr; 
N : integer); 
VAR 


count, F : integer; 
S : str255; 

myT : integer; 

myH : handle; 

myR : rect; 


FOR count := 1 TO 16 DO 
BEGIN 
CASE count OF 
1: 


:= count + 1; 
12, 13, 14, 15, 16: 
F := count + 8; 
OTHERWISE 
ND; 


М 
бе{Еоп{Мате(Е, 5); 
GetDItenCCP, N + count, тут, тун, МВ); 
IF S = ”” THEN 
HiliteControl(ControlHandle(myH), 255) 
ELSE 
HiliteControl(ControlHandleCmyH), 0); 
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END; resource 'BNDL^ (-4064, purgeeble) ( 
END; 'epft^, 


( cdev Main Function. Handles InitDev call (Zaps 811 the ( /* array TypeArray: 2 elements */ 
unistalled Font Buttons and selects the current Font Button) /* (1) */ 

and the HitDev calls (selects the pressed Font Buttons and ^ [CN* ^, 

sets the Application Font to that Font. ) ( /* array IDArrey: 1 elements */ 


/* [1] €/ 
FUNCTION Mein; 0, -4064 
VAR ‚ 
Val : longint; /* [2] */ 
IN 'FREF ', 
IF (cdevStorage €? 0) AND (cdevStorage € 1) AND ( /* array IDArrey: 1 elements */ 
(cdevStorage <> -1) THEN /* (1) */ 
BEGIN 0, -4064 
CASE Message OF ) 
Ж (InitDev) ) 
BEGIN ); 


ZepFontsCCPDialog, numitems); 

DoHitCCurNum + numitems, numitems, CPDialog); resource 'FREF^ (-4064, purgeable) ( 
қ ‘cdev’, 

1: (HitDev) : 

BEGIN i 


DoHitCitem, numitems, CPDialog); 
SetNunCitem - numitems); 


END; 
OTHERWISE 
END; 
END; 


Main := cdevStorage; 
END; 


/* 
* AppFont.r - Application Font Control 


х by Steve Sheets in MPW Format 
* Control Panel Proc changes Application Font 
x 


*/ 
* include “Types.r’ 
type ‘apft’ as ‘STR '; 


type ‘nrct’ ( 
integer = $$CountOf (RectArray); 
array RectArray ( rect; ); 

Р 


type ‘mach’ ( 
unsigned hex integer; 
unsigned hex integer; 


2 


resource ‘apft’ (0) ( 
“Application Font Control by Steve Sheets 3/18/87” 
; 

resource 'nrct^ (-4064, purgeable) ( 
/* array RectArray: 1 elements */ 
/* (1) */ 
(- 1,87, 206,322) 

); 


resource ‘mach’ (-4064, purgeeble) ( 
OxFFFF, 
Ü 


); 
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); 


resource “ІСМ8” (-4064, purgeeble, preload) ( 


) 


( 


) 


/* array: 2 elements */ 

/* (1) */ 

$"1FFF FFF8 2000 0004 4002 0002 8006 0001" 
%”800Е 0001 8016 0001 8026 0001 8046 0001" 
%”80ҒЕ 0001 8106 0001 8206 0001 8406 0001" 
$^8806 0001 ВҒІҒ 8001 8000 0001 8000 8001" 
%”8001 5001 8002 3001 8001 1001 8000 9101" 
$°8001 F281 8000 0441 8000 0821 8000 1001" 
%”8000 2129 8000 1290 8000 0910 8000 04Е0” 
%”8000 0281 4000 0102 2000 0004 ІҒЕҒ FFF8", 
/* (2) */ 

$^1FFF FFF8 3FFF FFFC ТЕРЕ FFFE FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
$"FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF^ 
$^FFFF FFFF FFFF FFFF FFFF FFFF FFFF ҒҒҒҒ” 
$^FFFF FFFF 7FFF FFFE 3FFF FFFC 1FFF FFF8" 


resource 'DITL^ (-4064, purgeable) ( 


/* аггау DITLerray: 17 elements */ 
/* [1] */ 
(25, 100, 44, 170), 
RadioButton ( 
enabled, 
“Chicago” 


4 
/* (2] */ 
(45, 100, 64, 185), 
RedioButton ( 
enabled, 
“New York’ 


7 
/* [3] */ 
(65, 100, 84, 169), 
RedioButton ( 
enabled, 
“Geneva” 


), 

/* [4] */ 

(85, 100, 104, 171), 

RadioButton ( 
enabled, 
“Monaco” 
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), 
/* [5] */ 
(105, 100, 124, 164), 
RedioButton ( 
enabled, 
enice” 


4 
/* [6] */ 
(125, 100, 144, 167), 
RedioButton ( 
enabled, 
“London” 


/* (7) */ 
(145, 100, 164, 165), 
RedioButton ( 
enebled, 
“Athens” 


/* [8] */ 
(165, 100, 185, 209), 
RadioButton ( 
enabled, 
“San Francisco” 


4 
/* [9] */ 
(25, 215, 44, 284), 
RedioButton ( 
enabled, 
“Toronto” 


д 
/* [10] */ 
(45, 215, 64, 270), 
RedioButton ( 
enabled, 
“Cairo” 


/* [11] */ 
(65, 215, 84, 313), 
RedioButton ( 
enabled, 
“Los Angeles” 


/* [12] */ 
(85, 215, 104, 272), 
RedioButton ( 
enabled, 
“Times” 


д 
/* [13] */ 
(105, 215, 124, 297), 
RedioButton ( 
enabled, 
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“Helvetica” 


/* [14] */ 

(125, 215, 144, 283), 

RedioButton ( 
enabled, 
“Courier” 


9 
/* [15] */ 
(145, 215, 164, 283), 
RedioButton ( 
enebled, 
“Symbol” 


/* [16] */ 

(165, 215, 184, 284), 

RedioButton ( 
enabled, 
“Taliesin” 


/* (17) */ 

(5, 129, 23, 364), 

StaticText ( 
disabled, 
“Select New 
Application Font’ 


PROGRAM AF Test; 
VAR 


X, F, N : integer; 
SP : SysPPtr; 
E : OSErr; 
BEGIN 
SP := GetSysPPtr; 
F := SP^.Font; 
x := 2; 
АЗЕ X OF 
BEGIN 
N := NewYork; 
SP^.Font := N- 1; 
E := WritePerem; 
END; 
OTHERWISE 


D; 
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ABC's of Macintosh 
Code Tester Shell for Pascal 


Writing code for the Macintosh can be a very tedious process, 
unless you start with a shell program. The program in this 
example is designed to provide a simple shell supporting a 
window, menus, text edit and update events. You can select a 
desk accessory, move the window, zoom the window, and close 
the window. The window supports a text edit record and some 
quickdraw graphics, both of which are updated whenever the 
window is uncovered. The purpose of this shell program was to 
provide a simple working Macintosh program, which could then 
be used to test specific code examples. So I've called it Code 
Tester! The routines to be tested are placed in the TestStuff Unit. 
I've coded two routines called ‘theTest’, which displays some 
text edit message, and ‘theDrawing’, which draws some quick- 
draw stuff in color (if you have a Mac IT). You can use this code 
tester shell to quickly test out procedures that will become a part 
of a larger Mac program, without having to re-invent the event 
loop programming of windows, events, menus and so forth. If 
you are new to Mac programming, this will also give you a good 
overview of how a Mac program is constructed. The black and 
white output of code tester is shown in figure 1. 

This program was first written in TML Pascal using TML's 
syntax of segmentation. The version presented here is written in 
LS Pascal using units instead of segments. It should be easily 
ported to either Turbo Pascal or back to TML Pascal. The 
program globals are placed in one unit, while the main program 
and the test unit make up the other two units. 


LS Pascal 1.11 and the Macintosh Il 


The latest version of TML Pascal that I have is 2.2 which I 
used on this program. For LS Pascal, the latest version is 1.11 
which is officially a ‘beta’. Think is distributing version 1.11 as 
a patcher program plus libraries that will automatically update 
your version 1.0 LS Pascal into the 1.11 version. This version 
runs on the Mac II and supports the new Mac II libraries. 
However, there are still problems in using the LS shell environ- 
mentto run, debug and edit your programs. Apparently, not all of 
the system parameters required for a color video board on a Mac 
II are being properly reset and if you have your video set to 256 
colors, you may find yourself crashing a lot when editing and 
running under the LS shell. Think is still trying to get all the bugs 
out of this. In black and white mode, this version seems very 
reliable on the Mac II. 

Mac programs written in Pascal tend to have a very small 
main program. Find the end of the program listing ‘CodeTester’, 
and you'll see our main program has only four items: PrimeMem- 
ory, MainSetUp, MainEventLoop and Close. 
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code Application 


Code Tester Ss 


B This is a Test! 
B Put your test code here..| 


Fig. 1 Text Edit, & Color Quickdraw (on a Mac Il!) 


Does Anyone Understand Memory Management? 


The first procedure called is Prime Memory. This routine is 
called first to do some memory management for us. A typical 
thing is to allocate additional master pointers and set up a grow 
zone proc in case we run out of memory. It is also possible to do 
some heap management such as calling MaxApplZone to grow 
the heap to the application limit. However, this might not be 
considered *MultiFinder friendly’ when we start dividing the 
heap into seperate application zones. As MultiFinder becomes 
available, and Inside Macintosh Volume 5 gets ‘debugged’ from 
all it's errors, hopefully a more clear picture of how memory 
management is properly done will emerge. While I have not 
placed a grow zone proc in our program, an example is given 
here. А program's grow zone function is called by the Memory 
manager when it needs a larger continuous chunk of memory 
then it has available. As usual though there are a couple of pitfalls 
here. I constructed this straight from IM and hope that I am 
correct. Memory management seems to be the most misunder- 
stood of all Mac subjects and more information in this area would 
be welcome at MacTutor. 


FUNCTION MyGrowZoneCcbNeeded : Size) : LongInt; 
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Ver 
AHandle : Handle; 
Begin 
If NOT GZCritical Then 
MyGrowZone := 0 (don't respond, post failure ) 
LSE 


Begin 
AHaendle := GZSaveHnd; 
If AHendle = NIL Then 
Begin 
SetFontLockCFALSE); 

(* Anything else *) 

MgGrowZone :=1; (we freed some) 

End (AHendle = NIL) 
ELSE 


( handle in danger? ) 
(dump something ) 


MyGrowZone := 0; 


End; (First Else, AHandle :=) 


End; 


Another heap management routine that could be called in our 
"PrimeMemory' routine is one to set the application heap limit. 
Again, under MultiFinder, this probably would not be desirable 
since MultiFinder is allocating each application it's own heap 
space based on the size resource in the resource file. Also, this 
command seems to choke LS Pascal's shell environment, so I 
have left it out of the code. 


SetApplL imitCPOINTERCORD4CGetApplL imit2-4096)); 


What we are trying to do here is to add about 4k to the initial 
8K stack size at start-up. 

Then (Last but not least) we call MoreMasters. For EACH 
MoreMasters call we obtain 1 Master Ptr. block with 64 master 
pointers for the use of the program. All of our handles we declare 
in the program will use one of these master pointers. 


Initializing the Macintosh Managers 


Going back to the Main program, next comes *MainSetUp', 
which collects all the init type calls. In the routine ‘Energize’ is 
the standard Macintosh inits for quickdraw, menus, fonts and so 
forth. One thing that is always handy is to place a pointer to a 
crash routine in the call to InitDialogs(). This will direct the Mac 
to your crash proc when the user hits the resume button during a 
system bomb. This could prevent damage from a system reset. In 
our program, our crash proc just returns to the Finder. Take a look 
at how the cursor is set up, course you don't have to do it like this 
if youdon’t wantto. Here again justa convenience. Note the type 
coercion in the HLock call. HLock expects a HANDLE, not a 
CURSHANDLE. Watch (no pun) the spelling of curshandle. 
CursorHandle is wrong, and it's real easy to do. Also watch out 
for ICN# NOT ICON+# it can be a really frustrating experience 
(I've done it twice now sigh). 

The other set up troutines are for a window, text edit, rec- 
tangles and menus. In our program, we have only two menus so 
this is pretty straight forward. The SetUpLimits routine is used to 
set our rectangles. Note here that we set the rectangle for our 
window in relation to the screenbit.bounds global variable. This 
variable is managed by Quickdraw and by referencing it, our 
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window will open up to a size that is appropriate to whatever 
monitor our program is running on. All window manager rec- 
tangles should be defined in relation to screenbits.bounds so that 
they will be independent of the display being used. In setting up 
text edit, we define the view area for text edit in relation to the 
window's port rectangle, then call TENew. This will associate а 
text edit record with this window. Note that the current grafport 
for quickdraw must be set to the window before TENew is called. 
This is so Text Edit can access the quickdraw globals for the text 
size, font, style and mode. In our program, we call SetUpWindow 
first, then call SetUpTE second, so everything is done іп the right 
order. 


The Main Event 


The main event loop is of course, the heart of all Macintosh 
programs. Our event loop calls system task, idles the text edit 
cursor and gets an event. Under MultiFinder, you might want to 
replace GetNextEvent with WaitNextEventif your program does 
not use null events. This will allow more time for MultiFinder to 
give to other applications that might be running in background 
during null events. Our program will process a mouse event, a 
menu key event, an activate/deactivate event and an update 
event. In our case, the activate event is trivial. All we do is call 
TEActivate, which sets the caret at the insertion point so it will 
blink when ТЕІ Ее is called. However, since we don't һауе any 
typing implement in our keydown event, this isn't of much 
interest. 


The Mighty Update Event 


Update events are the soul of the Macintosh. Mac guidelines 
suggest that all drawing on the Mac be done during an update 
event. The way this is done for text as an example, is to set up the 
text edit record and then invalidate an area of the screen. When 
the update event is generated, our update routine calls TEUpdate, 
and the text is automatically displayed. This is what we do in our 
"theText' procedure. We don't actually draw any text in the 
window. We just stuff it into our text edit record and invalidate 
the portrectangle of our window, generating an update event. But 
what about graphics? To update the graphics portion of our 
screen, wecallour drawing routine. This requires that all drawing 
calls be stored so that they can collectively be called any time an 
update event takes place, re-drawing the display. This is where 
the Mac can get tricky when your drawing calls are user gener- 
ated! In our update routine, we erase the port rectangle and re- 
draw the graphics by calling ‘theDrawing’ procedure. Note that 
we really are not erasing the whole window, nor does the whole 
window get re-drawn! When we call BeginUpdate, the visiRgn 
of the window is temporarily restricted to the update region so 
only the update region actually gets erased and re-drawn. After 
calling EndUpDate, the visiRgn is restored and the update region 
is left empty. The window manager is doing a lot of work behind 
the scenes during an update event. 
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Mouse Down Event 


When we have a mousedown event, our event loop calls 
DealwithMouseDowns and here we find where the mouse event 
took place by calling FindWindow, and then we use a case 
statement to deal with each area a mouse can be in. If itis a menu 
bar click, we call our menu bar routines. If it is a click in a desk 
accessory or a window not belonging to us, then we call Sys- 
temClick, which passes the event on to the desk accessory. For 
aclick in the content region of our window, we call SelectWin- 
dow to bring it to the front if it isn't already. For the drag bar or 
the goaway box in the window frame, we have toolbox calls that 
allow us to drag the window or hide the window. Note that we do 
not close the window, since one of our menu bar routines allows 
us to show the window and draw in it and that might be a big 
difficult if we closed the window and released the window 
record. In fact it would bomb! So HideWindow is sufficient. For 
a zoom box click, we erase the port rectangle of the window and 
call ZoomWindow, which generates an update event, so the 
window contents will be re-drawn. See how important it is that 
all window drawing be re-producable during an update event? 
ZoomWindow is a relatively new routine described in Inside 
Macintosh, volume 4. 

Our menu bar is pretty simple since it only has an apple menu 
and a file menu. Thus desk accessories are not properly sup- 
ported, since there is no edit menu for them! However, desk 
accessories can be called if they can be used with just a mouse 
click. We call GetItem to find the name of the desk accessory, and 
then pass that name to OpenDeskAcc, which runs the da. To 
protect ourselves from sloppy da’s, we save our current grafport 
while the da is running. 

If we select our ‘about...’ item in the Apple menu, the about 
dialog box comes up. One neat thing about the about box (did I 
really say that?) is it doesn’t have an “OK” Button. It was 
implemented by enabling the static text in the “R” file. What this 
means is that the text will be counted as an "ItemHit". Clicking 
anywhere in the dialog box will result in closing the about box. 
Please note however that if you DO use a button, the Stat Text 
should be “Disabled” so an item hit won't be reported. Rmaker 
assumes(theres that word again) that things are “Enabled” unless 
you tell itotherwise. The static text rectangle is defined to fill the 
entire about box, use carriage returns "QD" and be sure that you 
have notdisabled the text. Since Rmaker will enable it by default, 
when the user clicks you get an itemhit and dump the about box. 


How To Make (or steal) Your Own Icon’s 


First of all your going to need these programs (Tools). 


ResEdit! .01 REdit 
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The Easiest way is to launch ResEdit, then open a “New” 
window. Call the window anything you like, but don’t use the 
programs name you got it from, then go to a program and “Open” 
it..... 

OK now open the ICN# resource. “Copy” it, then: 

Paste it into your “New” window. 

Close the Program you opened. 


“Get Info” on your icon and set the ID to what you need, 
usually 128 for an application or 129 for it’s document. Modify 
the icon with the pencil to make what you want. 

Close and save it. 


Quit. 6 
Now launch v 


REdit 


Open the icon and choose "Decompile" and be sure to save the 
file. 


Quit. 


All Right !! You did it! 


You now have one file containing your icon, which can be 
"Paste" into any Resource file and one file with a “Hard copy” 
of the Icon which you can use in a Rmaker .R file. Thats how 
Code Tester's was done, my particular favorite way of doing it. 

Don't forget to launch Edit first and then the rsrc. doc since 
the decompiled icon file is not of type EDIT. 

That's all folks, may the mouse be with you. 


PROGRAM CodeTester ; 
(* Version 1.1 *) 
үй ) CopyRight 1987 by J.E.Fox, for Mactutor™ *) 
I- 
USES 
К0М85, TestGlobals, TestStuff; 


PROCEDURE crash; 
BEGIN 

ExitToShel1; 
ND; 


2 


PROCEDURE DoAbout ; 
VAR 


MyAbout : DialogPtr; 
ItemHit : Integer; 
BEGIN 
MyAbout := GetNewDialogCAboutId, NIL, Pointer(-1)); 
ShowW indow(MyAbout 2; 
ModalDialog(NIL, ItemHit); 
CASE ItemHit OF 
1 . 


DisposDialog(MyAbout); 
OTHERWISE 
BEGIN 
END; 
END; (* Case of х) 
END; Сх DoAbout *) 


PROCEDURE ProcessMenu_in CCodeWord : longint); 
VAR 
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Мепи № : integer; (menu number selected) 
Iten.No : integer; (item in menu selected) 


Мате : Str255; (neme holder for de or font) 


OpenDAResult : integer; 
TempPort : Grafptr; (protect against DA) 
BEGIN 

IF CodeWord € 0 THEN 
BEGIN (go ahead and process the command) 
Menu.No := HiWord(CodeWord); (get Ні word of...) 
Item.no := LoWord(CodeWord); (get Lo word of...) 
CASE Menu. No ОҒ 


N 
iris Iten-No OF 


DoAbout ; 

OTHERWISE 

BEGIN 
GetItenCAppleMHandle, Item No, Name); 
GetPortCTempPort); 
OpenDAResult := OpenDeskAcc(Name); 
SetPort(TempPort); 

END; (* Otherwise *) 

END (* Case Item.No of *) 
END; (* apple menu *) 


CASE Item. No OF 
1: 


theTest; 

2 3 
BEGIN С The dividing Line *) 
END; 


BEGIN 
SetCursor(Watch); 
Finished := True; (* quit *) 


END; 
END; (% Item.No of (File) *) 
END; (* file menu *) 
END; (* Case Menu_No of *) 
HiliteMenu(0); (* unhilite after menu *) 
END; (* the If codeword 00 *) 
END; (% of ProcessMenu_in procedure *) 


PROCEDURE DealwthMouseDowns (Event : EventRecord); 
VAR 


WindowPointedTo : WindowPtr; 
GlobalMouse, LocalMouse : Point; 
WindoLoc : integer; 
TempPort : GrafPtr; 

BEGIN 


GlobalMouse := Event Where; 
LocelMouse := GlobalMouse; 
GlobalToLoca!(LocalMouse?; 
WindoLoc := FindWindow(GlobalMouse, WindowPointedTo); 
CASE WindoLoc OF 
inMenuBer : 
ProcessMenu_in(MenuSelect(GlobalMouse)); 
inSysWindow : 
SystemClick(Event, WindowPointedTo); 
inContent : 
BEGIN 
IF WindowPointedTo € FrontWindow THEN 
BEGIN 


SelectWindow(WindowPointedTo); 
SetPortCWindowPointedTo); 


END; 
END; (InContent) 
inGrow : 
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BEGIN 
DragWindow(WindowPointedTo, GlobalMouse, ОгадАгеа); 
inGoAway 
BEGIN 
IF TrackGoAway(WindowPointedTo, GlobalMouse) THEN 
HideW indow(WindowPointedTo); 


END; 
InZoomIn, InZoomOut : 
IF TreckBoxCWindowPointedTo, GlobalMouse, WindoLoc) THEN 
BEGIN 


GetPortCTempPor t ); 
SetPort(WindowPointedTo); 
EreseRect(WindowPointedTo*^ .por tRect); 
ZoomW indow(WindowPointedTo, WindoLoc, True); 
SetPort(TempPort); 
END; 

END; 

OTHERWISE 
BEGIN 


END; 
END; С CASE WindoLoc of *) 
END; (* DealwthMouseDowns *) 


RS DealwthKeyDowns (Event : EventRecord); 
А 


CharCode : char; 
BEGIN 
CharCode := Chr(Event.message MOD 256); 
IF BitAnd(Event.modifiers, CmdKey) = CmdKey THEN 
ProcessMenu_in(MenuKey(CharCode)); 
END; 


PROCEDURE ActivateDeActivate (Event : EventRecord); 
VAR 


TargetWindow : WindowPtr; 
BEGIN 
TargetWindow := WindowPtr(CEvent.message ); 
IF Odd(Event modifiers) THEN 
BEGIN (= then the window is becoming active *) 
Se tPort(Targe tWindow); 
TEActivate(JeffsText); 
END (* If Odd *) 
ELSE 
BEGIN 
TEDeact ivateCJef fsText); 
END; (* Deactivate *) 
END; (% Activate.DeActivate *) 


PROCEDURE DealwthUpdates (Event : EventRecord); 
VAR 
UpDateWindow, TempPort : WindowPtr; 
IN 


UpDateWindow := WindowPtr(Event . message); 

GetPortCTempPort); 

Se tPor tCUpDateWindow); 

Beg inUpDateCUpDateWindow); 
EreseRectCUpDateWindow^ .portRect); 
MoveHHiChandleCJeffsText))2; 
HLockChandleCJef f sText)); 
TEUpdateCUpdateWindow^.portRect, JeffsText); 
theDrawing; {update our graphics stuff) 
HUnlockChandleCJef fsText)2; 

EndUpDate(UpDateW indow); 

SetPor t(TempPort); 

END; 


PROCEDURE MainEventLoop; 
VAR 
Event : EventRecord; 


BEGIN 
REPEAT 
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SystenTesk ; 
TEIdleCJef fsText); 
IF GetNextEvent(EveryEvent, Event) THEN 
CASE Event.what OF 
mouseDown : 
DealwthMouseDowns(Event); 
KeyDown, AutoKey : 
DealwthKeyDowns(Event); 
ActivateEvt : 
ActivateDeActivateCEvent); 
UpDateEvt : 
DealwthUpdates(Event ); 
OTHERWISE 
BEGI 
END; 
END;(* of Case х) 


UNTIL Finished; 


END; 
PROCEDURE Pr imeMemory; 
BEGIN 


Grow Heap to Limit } 
(* Allot 5, 64 Mptr Blocks *) 


(MaxApp IZone; 
MoreMasters; 
MoreMasters; 
MoreMasters; 
MoreMasters; 
MoreMasters; 


END; 
PROCEDURE Close; 
BEGIN 


END; 


сх Bag Following ere called by Set Up ШАШЫ *) 
PROCEDURE Energize; 
VAR 


Bean, WatchH : CursHendle; 


BEGIN 


InitGraf(@thePort); 
InitFonts; 
InitWindows; 

Ini tMenus; 

TEInit; 
InitDialogs(@crash); (* crash Proc to ‘Resume’ *) 
InitAllPecks; 

FlushEventsCeveryEvent, 0); 


(* Set up all Managers *) 


WatchH := GetCursor(watchCursor); (watchs Mptr addr stack) 
HLockCHandleCWatchH)); (% Note the type clash *) 

Watch := WatchH**;(* DDeref and store *) 

SetCursor (Watch); (% Wrap 10 Mr. Sulu *) 

Finished := False;(* program terminator *) 


END; 

PROCEDURE SetupMenus; 

BEGIN 
AppleMHendle := GetMenuCAppleMenu); 
InsertMenuCAppleMHandle, 02; 
FileMHandle := GetMenu(F i leMenu); 


InsertMenu(F i leMHandle, 0); 
AddResMenuCAppleMHandle, 'DRVR/); 


MoveHHICHandleCAppleMHandle)); 
HLockCHendleCAppleMHandle)); 
MoveHHIChandleCF ileMHendle)); 
HLockCHandleCF i leMHandle)); 
DrawMenuBar ; 

END; 


PROCEDURE SetupL inits; 
BEGIN 
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Screen := ScreenBits.Bounds; 

SetRectCDregArea, Screen.left + 4, Screen.top + 24, 
Screen.right - 4, Screen.bottom - 4); 

SetRectCGrowArea, Screen.left, Screen.top + 24, 
Screen.right, Screen.bottom); 

SetRect(WindowArea, Screen.left + 10, Screen.Top + 40, 
Screen.right - 200, Screen.bottom - 50); 
END; 


PROCEDURE SetUpW indow; 
VAR 


title : str255; 
BEGIN 


title := ‘Code Tester’; 


JeffsWindow := NewWindow(NIL, WindowArea, title, FALSE, 8, 


pointer(-1), TRUE, 1); 
IF JeffsWindow = NIL THEN 


crash; 
SetPortCJef fsWindow); 
TextFontCepplFont); 
TextSizeC 12); 
TextFaceC( 12; 
Tex tModeC 1); 
END; 


PROCEDURE SetUpTE; 

BEGIN 
WITH Jef fsWindow* .portRect DO 
BEGIN 


SetRect(ViewArea, left + 4, top + 4, right - 1, bottom - 1); 


END; 

DestArea := ViewAres; 

JeffsText := TENew(DestArea, ViewArea); 
( must be done after setPort) 
END; 


PROCEDURE MainSetUp; 
BEGIN 


Energize; 

SetupMenus; 

SetupL inits; 

SetUpWindow; (% Save Room for windows if used *) 
SetUpTE; 

InitCursor; (* reedy to go, show Arrow cursor *) 
END; 


BEGIN 
Pr ineMemory; 
MainSetUp; 
MainEventLoop; 
Close; 

END. 


UNIT TestGlobals; 
INTERFACE 


USES 
ROM85; 


CONST 
AppleMenu = 256; 
FileMenu = 257; 
TestItem = 1; 
Quititem = 3; 


AboutId = 260; 
NoteId = 261; 
CautionId = 262; 
StopId = 263; 


(* Resourse ID's *) 


Q The Essential MacTutor, Vol. 3 


(set the size of the screen) 


DlogH = 100; 
DlogV = 85; 


(* for SF Get & Put *) 


UntitledId = 300; (* Strings *) 


Seveit = 301; 
UndoIt = 302; 


VAR 
Finished : Boolean; 
Watch : Cursor; 


(* terminate program *) 
(* Cursors *) 


AppleMHandle, FileMHandle : MenuHandle; 


ResStr : Str255; 
ResStrHdl : StringHandle; 
Machine : integer; 


DragAres : Rect; 
GrowArea : Rect; 
Screen : Rect; 
ViewArea, DestArea : Rect; 
WindowArea : Rect; 


JeffsText : TEHandle; 


(* rectangles *) 


JeffsWindow : WindowPtr; (* ptr to window *) 


IMPLEMENTATION 
END. 


UNIT TestStuff; 
INTERFACE 


USES 
ROM85, TestGlobals; 


PROCEDURE theTest; 
PROCEDURE theDrawing; 


IMPLEMENTATION 
PROCEDURE theTest; 
VAR 


strø, stri, str2 : str255; 
BEGIN 
strü := chrC13)5; 
SysBeep(1); (% for now *) 
ShowWindowCJef f Window); 
ForeColor(blackColor); 
stri := ‘This is а Test!’; 


str2 := ‘Put your test code here..’; 


TESetSelect(0, 0, JeffsText); 


TESetText(pointer(ORD(@str1) + D, length(str D, veffsText); 


TEInsert(pointerCORDCestr2) + 1), 
TEInsertCpointerCORDC@str2) + 1), 
InvalRect (Jef f sWindow^ .portRect); 
END; 


PROCEDURE theDrawing; 
VAR 


r : rect; 
BEGIN 

PenSize(3, 3); 
PenMode(patCopy); 
PenPat (black); 
ForeColor(redColor ); 
BackColor(whiteColor); 
MoveTo(40, 20), 
SetRect(r, 40, 40, 80, 100); 
FrameRect(r); 
OffsetRect(r, 10, 10); 
FrameRect(r); 


1, JeffsText); 
length(str2), JeffsText); 
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ForeColor(blueColor); 
OffsetRect(r, 10, 10); 
FrameRect(r); 
OffsetRect(r, 10, 18); 
FrameRect(r ); 
ForeColor(yellowColor); 
SetRect(r, 20, 130, 100, 180); 
FillüvalCr, dkGray); 
OffsetRect(r, 15, 15); 
ForeColor(greenColor); 
Fillüval(r, gray); 
OffsetRect(r, 15, 15); 
ForeColor(cyanColor); 
Fill0valCr, black); 
OffsetRect(r, 15, 15); 
ForeColor (magentaColor); 
Fill0val(r, 1tGray); 
ForeColor (blackColor ); 
END; 


END. 

х Code Tester .R resources 
* by Jeff Fox 

x 

Testor . RSRC 


Type COTE = STR 
0 0 by convention 


J. E. (JEFF) Fox Ver. 1.1 8 Feb. 1987 M9 J.E.Fox . 


Туре BNDL 
, 128 
COTE 0 
ICN® 1 
0 128 1 129 
FREF 2 
0 128 1 129 


Type FREF 
‚ 128 


APPL Ø ;; local id 0 for icon list 


‚ 129 


TEXT 1 ;;Doc's File Type, Local id 1 for icon list 


x — Multifinder —— 
Төре SIZE = GNRL 
-1 
2 


41 
16384 ;; $4000 = bit 14 set 
L 


223232 3, 200K less 32K =220K (for 250К recomended) 
.L 
172032 ;; 200K less 32K = 120K (for 200K minimum) 


Type ICN* = GNRL 
‚128 (4) ;; The Appl. Icon 
H 


FFFFFFFF (0000003 BFFFFFFD 40000005 
А0000005 A0000005 10000005 А0000005 
А0000005 АЗЕСЗЕС5 0402005 А0402005 
А0402005 10402005 А0402005 А0402005 
А0403Е05 40402005 А0402005 А0402005 
А0402005 А0402005 0402005 А0403Ғ85 
А0000005 А0000005 10000005 А0000005 
А0000005 BFFFFFFO 0000003 FFFFFFFF 
x 


FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
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FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 


, 129 3, The Doc Icon 

.H 

OFFFFCOS 08000600 08000500 08000480 
0ҒЕ00440 09000420 090007Ғ0 09 1Ғ00 10 
09 1000 10 091000 10 09100010 091000 10 
08 1000 10 08100010 08 1-00 10 080000 10 
08007С 10 080040 10 08004010 08007010 
080040 10 080040 10 080040 10 080040 10 
080000 10 08ЕЕВ000 080000 10 08000390 
09АЕТ0 10 080000 10 080000 10 OFFFFFFO 
x 

QFFFFCO0 OFFFFEOS OFFFFFOO OFFFFF80 
OFFFFFCO OFFFFFE® OFFFFFFO OFFFFFFO 
OFFFFFF® OFFFFFFO OFFFFFFO OFFFFFFO 
OFFFFFFO OFFFFFFO OFFFFFFO OFFFFFFO 
OFFFFFFO OFFFFFFO ?FFFFFFO OFFFFFFO 
OFFFFFFO O0FFFFFFÜ OFFFFFFO OFFFFFFO 
QFFFFFFO OFFFFFFO 9FFFFFFO OFFFFFFO 
QFFFFFFO OFFFFFFO OFFFFFFO OFFFFFFO 


x 


MENUS ——— 


Type MENU 

* the apple menu 
M 

About Code Tester... 
(- 


Туре MENU 

* the file menu 
‚257 

File 
Run the Test/R 
(- 


Quit/Q 


* — Dialogs —— 
Type DLOG ;; About Box 
260 (4) ;; Purgeable 
Mikey Likes it !! 5; Title String 
60 110 195 430 ;; H,V, Global 
Visible NoGoAway 
3 
0 
270 


* — Alerts -- 
Туре ALRT 
,261 (4) ;, Note Alert #1 in List 
100 100 200 400 
211 
F764 


Type ALRT 
, 262 3, Caution Alert 82 in List 
100 100 200 400 
212 
F765 


Type ALRT 
,263 ;; Stop Alert 83 in List 
100 100 200 400 
273 
F765 


x — Dialog Items —— 
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Type DITL 
‚2710 (4) j; AboutBox, Purgeable 
3, * of Items 


* 1 Static Text Items MUST be DISABLED 

ж Other wise mouse clicks reported for Text item. 

StatText 

22 170 410 3, H,V, Local, Zero 'D^ not ‘0D’. 

Code Test Version 1. 1\00\00++ 

For Run Time tests of соде\00\00++ 

М9 1987 by J. E. (Jeff) Fox, for Mactutor™\8D\8D++ 
All Rights Reserved 


Type DITL 
,271 (4) 3, Note Alert 
3, 8 of Items 
x] 
BtnI tem 


12 175 32 278 
OK 


*2 
Stat Disable 
50 10 190 390 
“0 


Type DITL 
‚2172 (4) ;; Caution Alert 
;; 8 of Items 


х] 
BtnItem 


12 175 32 280 
Okay with me 


22 

BtnI tem 

43 175 62 280 
Forget it 


x3 
Stat Diseble 
50 10 190 390 
“0 


Type DITL 
2273 (4) j; Error, Stop Alert 
2 3, * of Items 


ж] 

BtnItem 

12 175 32 295 
EXIT To Finder 


*2 
Stet Diseble 
50 10 190 390 
“0 


з — Strings —— 
Type STR 


‚300 (4) ;; For the window, If needed 
UnTitled 


‚301 (4) 
Mikey Likes it 


‚302 (4) 
What the &%$$$? 


cl 


EE, 
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Pascal Procedures 
Tear-Off Menus Explained 


Hello once again, this month I would like to show how to 
implement tear-off menus. What is a tear-off menu? It is a menu 
which can be removed from the menu bar and used as a window. 
I first saw a tear off menu in a pre-release version of Hypercard 
by Bill Atkinson. Since I have had a lot of experience creating 
and using Menu and Window Definition routines, I thought I 
would try to duplicate his implementation of tear-offs so that 
MacTutor readers can see how it is done and use them in their 
Own programs. 

I assume that you know how menu and window definition 
routines work. If you are not familiar with them read my articles 
in the July, August, and October 1986 issues of MacTutor. 

The Window Definition routine used in the example is 
fairly straight forward, and, in fact, really isn't needed. It's sole 
purpose is to NOT look like a regular window. To do this I made 
the window'stitle bar small and solid black. The pattern drawing 
is not a part of the definition routine. It is handled in a update 
eventasany other window'scontents. The window looks like the 
one in figure 1. 


АТАХ 
42.” 
over 

Фо ә 


% 


219% „м 
Haee 
.. 9,8 8 
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The Menu Definition routine used in the example is where 
the special tear-menu code is. The tear-off menu in figure 2 looks 
very similar to the tear-off window. The size and draw messages 
are just as you would expect. The choose message, however, has 
some special coding to implement the tear-off. When we get the 
choose message, and the mouse is outside of the menu rectangle 
we check to see how far outside it is. If itis more than 10 pixels 
outide of the menu rectange, then we do not return from the 


© The Essential MacTutor, Vol. 3 


Darryl Lovato 

TML Systems 

MacTutor Contributing Editor 
MacTutor Vol. 3 No. 12 


«e 


Pascal 


choose message routine. Instead, we drag a outline of the menu 
on the desktop region until the mouse comes up, the user moves 
the mouse over another menu, or the mouse is moved back onto 
the original menu. If the mouse comes up while we are tracking 
it, we send a message back to the program telling it to move and 
re-display the torn window at that point. We communicate this 
information by posting an event which is unused by the applica- 
tion. I picked event #12, but you could choose any of the 
application event numbers. We pass the top left coordinate of 
where to display the pallete window in the Event.message 
paramter. 

When the main event loop gets event 12, it must move the 
menu to the location passed in the message and display the 
window. 
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Figure #2 


There are a couple of things that need to be pointed out. 
First, drawing all the patterns is real slow (even on a MacII!!!). 
This could be improved a great deal by keeping a offscreen 
bitmap of the patterns and use copybits instead of drawing them. 
Second. I know I have done a big no-no by not making the menu 
and window defs code resources. Third, you should be able to 
edit the patterns by double clicking on them to bring up a pattern 
editor window. Fourth, it would be great if the patterns could be 
in color on a Mac II. I leave the above enhancements to you as an 
exersize. 

The program I used to create the tear-off windows is given 
below. It was written is TML Pascal, but the techniques shown 
should be usefull no matter what language your using. Have fun! 
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Pascal Code Optimizations 


I would like to share some secrets with MacTutor readers 
out there who strive for the fastest, smallest Pascal code. My 
tricks will not improve your code 500%, as re-designing a 
algorithm could, but they can help you get the most out of the 
code generated by your compiler. These tricks are for TML 
Pascal, but should help you generate better code in any Pascal. 


1. Always use Inc(x) and Dec(x) procedures instead of x := x + 
lorx:2x-1. The inc and dec procedures generate one 
assembler instruction as opposed to 3 for x := x + 1. This 
saves 6bytes each time you use it. When inc and dec are used 
in loops, this can save a lot of execution time. [Unfortua- 
nately, these are not available in other implementations. - 
Ed] 


2. If you pass a structure larger than 4 bytes to a procedure or 
function, pass it as a static paramter. When you use a static, 
instead of regular parameters, you save 18 bytes per par- 
amter in code size. This saves a lot of execution time, too. 
The reason for this is that when you pass a large structure as 
a static parameter, it is not copied local to the procedure. 
This is especially usefull if you pass a lot of strings to 
procedures and functions. 


3. In certain if. .then. .е1ѕе statements, you can save code by 
restructuring the statement to eliminate the else, and 4 bytes! 


4. Forloops are code hogs! Because Pascal compilers check the 
bounds of ‘for’ loops before entering them, they generate a 
lot of error checking. By recoding a ‘for’ loop as a repeat 
loop you can save 16 bytes. Here is an example: 


Instead of this: 
for x := 1 to 100 do 
begin 


end; 


Do this: 
х := |]; 
repeat 
inc(x); 
until x = 100; 


There are a lot of other optimizations that can be done to 
make faster, smaller Pascal code, but these are the ones that can 
be used the most. Of course, re-writting the code in assembler 
would make the biggest diffrence in code size and speed, but 
that can take a long time and there are a lot of people who do 
not understand 680x0 assembler. 

[The following code has been sanitized to work in both TML 
Pascal and LS Pascal and has been tested in both. However, one 
of the functions that returns a rect as an argument tripped up the 
Turbo Pascal syntax checker, so some modification may be 
necessary to get the program compiled in Turbo. We are at a loss 
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as to why Turbo should be more picky than LS Pascal, which I 
thought was the most fussy of all! The code should also work fine 
in MPW, but we didn't take the time to actually try it. -Ed] 


We welcome Darryl back to MacTutor and present him with 
our Program of the Month award for this important and timely 
example of tear-off menus. One reader wanted it so bad, he made 
me send an advance copy of the article next day air so his 
department could get to work on it. Thanks Darryl! 


еә с ж сы сс ы EM e cO OMNCM а ҮМ 
Listing 1 TML & LS Pascal Source Code 


PROGRAM TeerMenu; 


( Exenple of tear-off menus) 

( by Derry! Loveto of TM. for MacTutor) 

( Inspired by HyperCerd) 

( TML Pascal / LS Pascal Version ) 

( Some modifications may be required for Turbo Pascal ) 
( Turbo Pascal does not seem to like a rect as ) 

( а return varieble from a function. ) 


uses MacIntf ; ( remove for LS Pascal ) 


($T APPL TEAR) ( remove for LS Pascal ) 
($8*) ( remove for LS Pascal ) 
($L TearMenuRes} ( remove for LS Pascal ) 


(global constants) 

CONST 
AppleMenuID = 1; 
FileMenuID = 2; 
EditMenuID = 3; 
grephicalMenu = 4; 
WindResID = 1; 
AboutID = 3000; 


(global variables) 
VAR 


myMenus : ARRAY[AppleMenulD..EditMenuID] OF MenuHandle; 
Done : Boolean; 
RegWDEFWindow : 

GrowArea : rect; 
DregArea : rect; 
myWindowPeek : WindowPeek; 

MyGraphicsMenu : menuhandle; 
currentPatWind : WindowPtr; 


NindowPtr; 


( My Window Definition Function ) 
FUNCTION MyWindowDef CvarCode : Integer; 


theWindow : WindowPtr; 
message : Integer; 
param : LongInt) : LongInt; 
TYPE 
RectPtr = ^Rect; 
VAR 


eRectPtr : RectPtr; 
nyWindowPeek : WindowPeek; 


( Nested procedures follow ) 
PROCEDURE DoDrewMessage CWindToDrew : WindowPtr; 
DrewPerem : LongInt); 


VAR 
TitleBarRect : Rect; 
CurrentY : Integer; 
index : Integer; 
GoAwayBox : Rect; 
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Show : boolean; 
WindowRec : WindowPeek; 
BEGIN 

WindowRec := WindowPeek(WindToDraw); 

Show := WindowRec^.visible; 

IF Show THEN 

BEGIN 

TitleBarRect := WindowRec^.strucRgn^^ .rgnBBox; 
IF ÜrewPerem © Ø THEN (just toggle goAway box) 


BEGIN 
WITH TitleBarRect DO 
BEGIN 
top := top * 3; 


left := left + 5; 
bottom := top + 8; 
right := left + 8; 
END; 
InsetRect(TitleBarRect, 1, 1); 
Inver tRect(Tit leBarRect); 


END 
ELSE (we need to draw the window frame} 
BEGIN 
PenNormal; 
FrameRect(TitleBarRect); 
TitleBarRect.bottom := TitleBarRect.top + 13; 


FrameRect(TitleBarRect); 
InsetRect(TitleBarRect, 1, 1); (shrink by 1) 
EraseRect(TitleBarRect); 


IF WindowRec* .hilited THEN 
BEGIN ( add hiliting ) 
FillRectCTitleBarRect, black); 
WITH TitleBarRect DO 
BEGI 

top := top + 2; 
left := left + 4; 
bottom := top + 8; 
right := left + 8; 


END; 
PenMode(CpatXor ); 


FrameRect(TitleBarRect); 
PenNormal; 


END; 


FUNCTION DoHitMessage (WindToTest : WindowPtr; 
theParam : LongInt) : LongInt; 


VAR 
globalPt : Point; 
eRect : Rect; 
GoAwayBox : Rect; 
tempRect : Rect; 
WindowRec : WindowPeek; 
BEGI 


N 
globalPt.h := LoWord(theParam); 
globalPt.v := HiWordCtheParem); 
WindowRec := WindowPeek(WindToTest); 
eRect := WindowRec^.strucRgn^^.rgnBBox; 
eRect.bottom := eRect.top + 12; (create tBar Весі) 
tempRect := WindowRec^.strucRgn^^.rgnBBox; 


IF PtInRect(globalPt, tempRect) THEN (in structure гоп?) 


BEGIN 
tempRect := WindowRec^ .contRgn** .rgnBBox; 


IF PtInRect(globalPt,tempRect) THEN (if content гоп) 


DoHitMessage := wInContent 
ELSE IF PtInRect(globalPt, aRect) THEN (drag) 
BEGIN 


IF WindowRec^.hilited THEN 


BEGIN (we need to check go-away box) 
WITH eRect DO 
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BEGIN 
top := top * 2; 
left := left + 4; 
bottom := top + 8; 
right := left + 8; 


END; 

IF PtInRectCglobalPt, aRect) THEN 
DoHitMessage := winGoAway 

ELSE 
DoHitMessage := wInDrag; 


ELSE 
DoHitMessage := wInDrag; 
END 


ELSE (it was in our window frame) 
DoHitMessage := wNoHit; 


END 
ELSE (it wasn’t in our window at all} 
DoHitMessage := wNoHit; 
END; 


PROCEDURE DoCalcRgnsMessage (WindToCalc : WindowPtr); 
VAR 


tempRect : Rect; 
eWindowPeek : WindowPeek; 
eRgn : RgnHendle; 
WindowRec : WindowPeek; 
BEGIN 
tempRect := WindToCalc*.PortRect; 


OffsetRectCtempRect, -WindToCalc^.PortBits.Bounds.Left, - 


WindToCalc^ .PortBits .Bounds. Top); 


TempRect.top := TempRect.top - 1; 
WindowRec := WindowPeek(WindToCalc); 
RectRgn(WindowRec^.contRgn, tempRect); 


InsetRect(tempRect, -1, -1); 

tempRect.top := tempRect.top - 12; 

RectRgn(WindowRec*.strucRgn, tempRect); 
END; 


( End of nested procedures ) 
BEGIN 
MyWindowDef := 0; 
CASE message OF 
wDrew : 
DoDrawMessage( theWindow, param); 
wHit : 
MyWindowDef := DoHitMessageCtheWindow, param); 
wCalcRgns : 
DoCalcRgnsMessage( theW indow); 
wNew : 


P 
wDispose : 
wGrow i 


END; (of case) 


J 


( function GetItemRectCitem : integer) : rect; ) 
FUNCTION GetItemRect Citem : integer) : rect; 
VAR 


tempRect : Rect; 
BEGIN 
WITH tempRect DO 
BEGIN 


top := ((Citen - D DIV 8) х 16) - 1; 
bottom := top + 17; 
left := (CCitem - 1) MOD 8) * 16) - 1; 
right := left + 17; 
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END; 
GetItemRect := tempRect; 
END; 


( procedure DrawPatWindow; ) 
PROCEDURE DrawPatwWindow; 
VAR 


i: integer; 
currentPat : Pattern; 
currRect : Rect; 
BEGIN 
FOR i := 1 TO 96 DO 
BEGIN 


currRect := GetI temRect(i); 
FrameRect(currRect); 
GetIndPattern(currentPat, 100, 1); 
FillRectCcurrRect, currentPat); 
FrameRect(currRect); 
END; 
END; 


(function GetMI temRect(whichRect: Integer ;myRect :Rect):Rect; ) 


FUNCTION GetMItemRect (whichRect : Integer; 
myRect : Rect) : Rect; 
VAR 


ItemRect : Rect; 
IN 


ItemRect := GetItenRect(whichRect); 
Of fSetRectCitemRect, myRect.left, myRect. top); 
GetMItemRect := ItemRect; 


д 
( procedure drewItem(myRect : rect; myItem : integer); ) 


PROCEDURE drewItem (myRect : rect; 
myItem : integer); 
VAR 


currentPet : pattern; 
IN 
IF (nyItem > 0) AND (nyIten < 97) THEN 
BEGIN 


myRect := GetMItemRectCmyItem, myRect); 
GetIndPattern(currentPat, 100, myltem); 
FillRect(myRect, currentPat); 
FrameRect(myRect); 

END; 
END; 


( procedure clearitem(myRect : Rect; lestCell : integer); ) 


PROCEDURE clearitem CmyRect : Rect; 
lastCell : integer); 
BEGIN 


DrewItem(nyRect, lestCell - 9); 
DrewItem(nyRect, lestCell - 8); 
DrewItem(nyRect, lastCell - 7); 
DrewItem(nyRect, lestCell - 1); 
DrewItem(nyRect, lestCel1); 

DrawItem(myRect, lestCell + 1); 
DrewItemCnyRect, lastCell + 7); 
DrewItem(myRect, lestCell + 8); 
DrewItem(myRect, lastCell + 9); 

END; 


( Menu Definition Routine ) 


PROCEDURE MyMenuDef (messege : Integer; 
theMenu : MenuHandle; 
VAR menuRect : Rect; 
hitPt : Point; 
VAR whichItem : Integer); 
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( Begin nested procedrues ) 
PROCEDURE DoDrawMessage (myMenu : MenuHandle; 


myRect : Rect); 
CONST 
MBerHeight = 20; 
VAR 


whichRect : Integer; 
currentPat : Pattern; 
currRect : Rect; 
BEGIN 
FOR whichRect := 1 TO 96 DO 
Drawitem(myRect, whichRect); 
END; 


FUNCTION DoChooseMessage (myMenu : MenuHendle; 
myRect : Rect; 
myPoint : Point; 
oldItem : Integer) : Integer; 

VAR 
currRect : Rect; 
alidone : boolean; 
whichRect : Integer; 
oldRect : Rect; 
mPt : Point; 
lestPt : Point; 
lestRect : Rect; 
menuPt : Point; 
tempRect : Rect; 
exitrect : rect; 
saveClip : RgnHandle; 
io : integer; 

BEGIN 

ClipRect(CmyRect); 
whichRect := 1; 
alldone := false; 
REPEAT 
currRect := GetMItemRect(whichRect, myRect); 
IF PtInRect(nyPoint, currRect) THEN 
alldone := true 
LSE 


whichRect := whichRect + 1; 
UNTIL CCAllDone? OR CwhichRect > 962); 
IF AllDone THEN ( if we are in а item) 
BEGIN 


IF (whichRect € oldiItem) THEN 
BEGIN 
IF ColdItem © 0) THEN 
ClearItemCmyRect, oldItem); 
InsetRectCcurrRect, -6, -6); 
PenSize(6, 6); 
PenPat (white); 
^ FremeRectCcurrRect); 
PenNormal ; 
InsetRect(currRect, -1, -1); 
FrameRect(currRect); 
END; 
DoChooseMessage := whichRect; 
END 
ELSE (че are not in a item) 
BEGIN 


IF olditem © 0 THEN ( invert the old item) 
clearitemCmyRect, oldItem); 
DoChooseMessage := 0; 


PenMode(notPatXOR); 

penpat(gray); 

exitrect := myrect; 

InsetRect(ExitRect, -10, -10); 

ExitRect.top := 20; 

menuPt.h := myRect.left + CCmyRect.right - 
myRect. left) DIV 2); 

menuPt.v := myRect.top + CCmyRect.bottom - 
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myRect.top) DIV 2); 
SetRect(tempRect, 0, 0, 0, 0); 
lestRect := tempRect; 
ClipRect(screenbits.bounds); 
EPEAT 
GetMouse(mPt); 
LocalToGlobal(mPt); 
IF CCLongint(mpt) <> LongintClastPt)) AND CNOT 
PtInRect(mpt, ExitRect)) AND (mPt.v > 20?) THEN 
BEGIN 
lestPt := mPt; 
tempRect := myRect; 
Of fSetRectCtempRect, mPt.h - menuPt.h, 


mPt.v - menuPt.v); 
IF tempRect.top « 20 THEN 
BEGIN 


tempRect.top := 29; 
tempRect.bottom := 20 + 202: 
END; 
FrameRect(ClastRect); 
FrameRect(tempRect); 
lestRect := tempRect; 


END; 
UNTIL (NOT button) OR ptInRect(mPt, exitrect) OR 
CmPt.v € 21); 
FrameRect(lastRect); 
PenNormal ; 
IF CNOT PtInRect(mpt, ExitRect)) AND (mPt.v > 20) 


BEGIN 
lestrect.top := lastrect.top + 12; 
io := PostEvent( 12,LongintClastRect . toplef t2); 
( this communicates back to the main event) 
( loop that а window was just torn from the) 
( menu. We pass the new topLeft in the message) 
END; 
END; 


THEN 


END; 


PROCEDURE DoSizeMessage СУАР myMenu : 
BEGIN 
WITH myMenu** DO 
BEGIN 
menuWidth := 127; 
menuHeight := 191; 
END; 


MenuHendle); 


END; 


( End of nested procedures ) 
BEGIN 
CASE message OF 
mSizeMsg : 
DoS izeMessage( theMenu); 
mOrawMsg : 
DoDrawMessage(theMenu, menuRect); 
mChooseMsg : 
whichItem :- DoChooseMessage( theMenu, menuRect, 
hitPt, whichItem); 
END; 
END; 


SS} 
( ShowAbout procedure ) 
PROCEDURE ShowAbout; 


VAR 
theDlog : DialogPtr; 
theItem : Integer; 
BEGIN 


theDlog := GetNewDialogCAboutID, NIL, Pointer(- 122; 
ModalDialog(NIL, theItem); 
DisposDialogCtheD10g); 


7 
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(  ProcessMenu procedure ) 
PROCEDURE ProcessMenu (codeWord : Longint); 
TYPE 
PetPtr = “Pattern; 


VAR 
menuNum : Integer; 
itemNum : Integer; 
NameHolder : str255; 


dummy : Integer; 
yuck : boolean; 
myPattern : Pattern; 
DeskPatternPtr : PatPtr; 
sevePort, aPort : grefPtr; 
theRgni, theRgn2 : RgnHandle; 
BEGIN 
IF codeWord € 0 THEN 
BEGIN 
menuNum := HiWord(codeWord); 
itemNum := LoWord(codeWord); 
CASE menuNum OF ( the different menus) 
AppleMenuID : 
IF itemNum « 3 THEN 
ShowAbout 
ELSE 
BEGIN 
GetItem(nyMenus[AppleMenuID], itemNum, Name- 
Holder); 
dummy := OpenDeskAcc(NameHolder ); 


END; 
FileMenuID : 
Done := true; 
EditMenuID : 
yuck := SystemEditCitemNum - 1); 
GraphicalMenu : 
IF ItemNum © 0 THEN 
BEGIN 
GetIndPattern(myPattern, 100, ItemNum); 
SetPortCcurrentPatW ind); 
BackPat(myPattern); 
ннан а Race 
END; 
HiliteMenu(C0); 
END; 
END; 


( Deal With Mouse Downs procedure ) 
PROCEDURE DealWithMouseDowns CtheEvent : EventRecord); 


location : Integer; 
windowPointedTo : WindowPtr; 
mouseloc : point; 
windowLoc : integer; 
VendH : Longint; 
Height : Integer; 
Width : Integer; 
currRect, myRect : Rect; 
newcell, LestCell : integer; 
thePt, LastPt : Point; 
i : integer; 
myPattern : 
BEGIN 
mouseLoc := theEvent.where; 
windowLoc := FindWindowCmouseLoc, windowPointedTo); 
CASE windowLoc OF 
inMenuBer : 
ProcessMenu(MenuSelect(CmouseLoc)2; 
inSysWindow : 
SystemClickCtheEvent, windowPointedTo); 
inContent : 


Pattern; 
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IF windowPointedTo €» FrontWindow THEN 
eee ыы | 


BEGIN 
IF RegWDEFWindow = windowPointedTo THEN 
BEGIN 
SetPortCRegWDEFW ігаои ); 
GetMouseClastPt); 
newCell := 8; 
lestCell := 9; 
myRect := RegWDEFWindow^ .portRect; 
зА tmouseup DO (track in pattern wind) 


GetMouse( thePt ); 
IF NOT PtInRectCthePt, myRect) THEN 
BEGIN (we moved outside the window) 
IF lastCell © 0 THEN 
cleerItem(myRect, 1аѕїСе11); 
lestCell := 0; 


FOR i := 1 7096 00 
IF PtInRectCthePt, GetItenRectCi2) 


THEN 
newCell := i; 
IF newCell <> lastCell THEN 
BEGIN 
IF ClastCell © 0) THEN 
Clearitem(myRect, lastCell); 
currRect := GetI temRect(newCell); 
InsetRectCcurrRect, -6, -6); 
PenSize(6, 6); 
PenPatCwhite); 
FrameRect(currRect); 
PenNormal ; 
InsetRect(currRect, -1, -1); 
FrameRect(currRect); 
lestCell := newCell; 
END; 
END; 
END; 
Clearitem(myRect, lastCell); 
GetIndPettern(myPettern, 100, newCell); 
SetPortCcurrentPatWind); 
BeckPet(nyPattern); 
EraseRect(currentPatWind* .portRect); 
END; 
END; 
inDrag : 
BEGIN 
DregWindow(windowPointedTo, mouseLoc, DragArea); 
SelectwWindow(windowPointedTo); 
END; 
inGoAway : 
IF TrackGoAway(windowPointedTo, mouseLoc) THEN 
HideWindow(windowPointedTo); 
END; 
END; 


( егі With Key Downs procedure ) 


PROCEDURE DealWithKeyDowns CtheEvent : EventRecord); 
TYPE 
Trick = PACKED RECORD 
CASE boolean OF 
true: 
long : Longint 


д 
false : € 
chr3, chr2, chr1, chr8 : char 
) 
END; 
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VAR 
CharCode : char; 
TrickVar : Trick; 
BEGIN 
TrickVar.long := theEvent .message; 
CharCode := TrickVar.chr; 
IF BitAndCtheEvent modifiers, CmdKey) = CadKey THEN 
(check for a menu selection} 
Sip ProcessMenu(MenuKey(CharCode 22 


( Deal With Updates procedure) 
Е DealWithUpdates CtheEvent : EventRecord); 


UpDateWindow : WindowPtr; 
tempPort : WindowPtr; 


BEGIN 
UpDateWindow := WindowPtr(theEvent .message?; 
GetPortCtempPort); 
SetPortCUpDateWindow); 
BeginUpDeteCUpDateWindow); 
EreseRect CUpDateWindow^ .portRect); 
IF UpdateWindow <> currentPatWind THEN 

DrewPatWindow; 

EndUpDeteCUpDateWindow); 
SetPortCtempPort); 

END; 


(  MainEventLoop procedure ) 
PROCEDURE MainEventLoop; 
VAR 


Event : EventRecord; 
ProcessIt : boolean; 
where : Point; 


SystemTask; 
IF GetNextEventCeveryEvent, Event) THEN 
CASE Event.what OF 
mouseDown : 
DealWi thMouseDowns(Event); 
AutoKey : 
DealWithKeyDowns(Event ); 
KeyDown : 
Dea lWi thKeyDowns(Event); 
UpdateEvt : 
Ж DealWi thUpdates(Event); 
BEGIN ( we return this when a window torn) 
where :- Point(Event.message); 
HideWindow(RegWDef Window); 
MoveWindow(RegWDefWindow, where.h, where.v, true); 
ShowW indowCRegWDEF Window); 
END; 
OTHERWISE 
BEGIN 
END; 
END; (of cese) 
UNTIL Done; 
END; 


( SetupMemory procedure ) 
PROCEDURE SetupMemory; 
VAR 
x : Longint; 
BEGIN 
(x := ORD4(ApplicZone) + 128000;) 


(SetApplLimit(Pointer(x22;) 
MaxApplZone; 
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MoreMasters; 
MoreMasters; 
MoreMasters; 
END; 


SetupLimits ) 
PROCEDURE SetupL inits; 
VAR 


Screen : Rect; 
BEGIN 
Screen := ScreenBits bounds; 
WITH Screen DO 
BEGIN 


SetRectC(DragArea, left+4, top*24, right-4, bottom-4); 
SetRect(GrowArea, left, top + 24, right, bottom); 
END; 

END; 


( MakeMenus procedure ) 


PROCEDURE MakeMenus; 
VAR 


index : Integer; 
BEGIN 
FOR index := AppleMenuID TO EditMenuID DO 
BEGIN 


myMenus[index] := GetMenuC index); 
InsertMenuCmyMenus[ index], 0); 


END; 

AddResMenuCmyMenus [AppleMenuID], ‘DRVR’); 
MyGraphicsMenu := NewMenu(4, 'Grephics"'); 
MyGraphicsMenu**.menuProc := NewHandle(@); 
MyGraphicsMenu**.menuProc* := PtrC@MyMenuDef ); 
CalcMenuSize(MyGraphicsMenu); 
Inser tmenuCMyGrephicsMenu, 0); 
DrawMenuBar ; 

END; 


PROCEDURE crash; 
BEGIN 

ExitToShel1; 
END; 


( Main Program Excecution Starts Here } 


BEGIN 


InitGraf (@thePor t ); 
InitFonts; 

InitWindows; 

InitMenus; 

TEInit; 
InitDielogsCécresh?; 
InitCursor; 

Done := false; 
FlushEventsCeveryEvent, 0); 


SetupLimits; 
SetupMemory; 
MakeMenus; 


RegWDEFWindow := GetNewWindow(WindResID, NIL, Pointer(-1)); 
myWindowPeek := WindowPeek(RegWDEFWindow); 

myWindowPeek* .windowDefProc :- NewHandle(0); 

myWindowPeek* .windowDefProc^ := PtrC@MyWindowDef ); 

SetWRef ConCRegWDEFWIndow, Ord4(MyGraphicsMenu)); 
currentPatWind := GetNewWindow(2, NIL, pointer(-1)); 
SetPortCcurrentPatWind); 

BackPat(gray); 

EreseRectCcurrentPatWind^ .portRect); 


MainEventLoop; 
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END. (thats all folkes!) 


Listing 2: TML Link File (Ignore for LS Pascal ) 
IPAS$Xf er 


/Globals -4 
TearMenu 

PAS$L ibrary 
macintf 
MacIntfGlue 
/Resources 
TearMenuRes 
/Bundle 

/Type APPL TEAR 
/End 


Listing 3: REZ version resource file 


resource 'BNDL^ С 128) ( 
‘TEAR’, 
0, 
( /* array TypeArrey: 2 elements */ 
/* [1] */ 
ICN’, 
( /* array IDArray: 1 elements */ 
/* (1) */ 
0, 128 


/* [2] */ 

FREF’, 

( /* array IDArrey: 1 elements */ 
/* (1) */ 
0, 128 


) 
); 


resource 'DITL^ (3000) ( 
( /* array DITLerrey: 3 elements */ 
/* (1) */ 
(155, 142, 180, 205), 
Button ( 
enabled, 
“Okay” 


д 
/* (2) */ 
(6, 5, 112, 361), 
SteticText ( 
disabled, 

A - Teer * 
“Menu -\n\nWritten by Darryl Lovato of TML ^ 
“Systems, Inc.\n\nThis program shows how to^ 
“ make a window tear off of a menu. Idea” 

* from Hypercerd by Bill Atkinson. in^ 


/* [3] */ 

(115, 5, 149, 361), 

StaticText ( 
enabled, 
“Complete Pascal source code for this pro” 
“gram is available from MacTutor Magazine” 


) 
) 
); 


resource 'DLOG^ (3000, preload) ( 
(58, 74, 244, 436), 
dBoxProc, 
visible, 


363 


); 


goAway, 
0x0 


3000, 
“New Dialog" 


resource ‘FREF’ (128) ( 


); 


APPL, 
0, 


resource ‘ICN®’ (128, purgeeble, preload) ( 


); 


( /* array: 2 elements */ 
/* (1) */ 
$"000F F400 007A Ғ000 OIFF F780 OSFF 7FEO" 
$°O7FF FFBO 08ҒВ FFD8 OFFF B578 1FDF F6FC^ 
$"1F7E E8BC 1E77 А074 3E37 807С 1С00 006C^ 
$°SFFO ЗЕЗС 2E38 633C 3DEO 3С24 1Е60 4C24" 
$° 1400 4004 1C00 0004 0С00 4008 0400 0038" 
%%0404 6028 0001 8038 0200 0078 0008 1050" 
$^0103 С060 0180 0140 0780 0040 7020 0440" 
$^4510 0820 4887 E050 4980 0088 TFFF FFF8", 
[х [21 */ 
$^000F F400 00ТЕ Ғ000 OIFF ҒҒ80 OFF ЕРЕй" 
$^07FF FFFO OFFF FFF8 ЕЕЕ FFF8 IFFF FFFC^ 
$^1FFF FFFC IFFF FFFC 3FFF FFFC 1FFF FFFC^ 
$^3FFF FFFC 3FFF FFFC 3FFF FFFC IFFF FFFC^ 
$^IFFF FFFC 1FFF FFFC 8FFF FFFB Ø7FF FFFB" 
$^07FF FFFB O3FF FFF8 O3FF FFFB BIFF FFFO" 
$"01FF FFEØ O1FF FFCO O7FF FFCO 7FFF FFCO" 

| $^TFFF ҒҒЕЙ ТЕРЕ FFFB ТРЕЕ FFFB ТЕРЕ FFFB" 


resource ‘MENU’ (1) { 


); 


textMenuProc, 
Ox7FFFFFFD, 
enabled, 
epple, 
( /* array: 2 elements */ 

/* [1] */ 

“About Tear Menu...^, nolcon, 4”, *", plain, 
/* [2] */ 

*-^, nolcon, *^, “”, plain 


) 


resource ‘MENU’ (2) ( 


); 


7 
textMenuProc, 
Ox7FFFFFFS, 
enabled, 
*File^, 
( /* array: 1 elements */ 
/* [1] */ 
“Quit”, noIcon, *Q^, *^, plain 


resource ‘MENU’ (3) ( 


tex tMenuProc, 
Ox7FFFFFFD, 
enabled, 
*Edit^, 
( /* array: 6 elements */ 
/* (1) */ 
“Undo”, noIcon, *Z^, **, plain, 
/* [2] */ 
*-*, nolcon, 4”, *^, plein, 
/* [3] */ 
“Cut”, nolcon, *X^, ~, plein, 
/* [4] */ 
“Сору”, noIcon, “С”, “”, plain, 
/* [5] */ 
“Paste”, noIcon, *V^, °”, plain, 
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/* [6] */ 
“Clear”, nolcon, **, *", plain 


); 

resource ‘WIND’ (1) ( 
(100, 100, 292, 228), 
documentProc, 
invisible, 
goAway, | 
0x0, 


); 

resource ‘WIND’ (2) ( 
(81, 143, 224, 327), 
documentProc, 
visible, 
goAway, 
0x0, 
“Current Pattern” 


); 

date ‘TEAR’ (0) ( 
$ 1854 6561 7220 4065 6Е75 2С20 6279 2044" 
$6172 7279 6620 4C6F 7661 746F^ 


resource “РАТ: / (100, purgeable) ( 
( /* array PatArray: 96 elements */ 

/* (1) */ 
$^FFFF FFFF FFFF ҒҒҒҒ”, 
/* (2) */ 
$^00FF 77FF DOFF ТТҒҒ”, 
/* (3) */ 
$"DD77 0077 0077 0077", 
/* [4] */ 
%”АА55 АА55 АА55 АА55", 
/* (51 */ 
$"55FF 55FF 55FF 55ҒҒ”, 
/* (6) */ 
$ AAAA ЛАЛА AAAA AAAA”, 
/* (7) */ 
$*EEDD BB77 EEDD BB77", 
/* (8) */ 
$6888 8888 8888 8888", 
/* (91 */ 
$°В130 0318 D8CÓ 0С80”, 
/* (10) */ 
$^58010 0220 0108 4004", 
/* (11) */ 
$^FF88 8888 ҒҒ88 8888", 
/% (12) */ 
$^rF80 8080 ҒҒ08 0808", 
/* [13] */ 
$780", 
/* (14) */ 
$8649 2000 0204 98", 
/* (15) */ 
$^8244 3944 8201 0101", 
/* [16] */ 
$^F874 2247 8F17 2271", 
/* E17) */ 
$"55A0 4040 550A 0404", 
/* (18) */ 
$"2050 8888 8888 0502", 
/% (19) */ 
$"BF00 BFBF 8080 BOBO", 
/* [20] */ 


/* (21) */ 

%”8000 0800 8000 08", 
/% (22) */ 

$8800 2200 8800 22", 
/* [23) */ 

$"8822 8822 8822 8822", 
/* (241 */ 

$ AADO АА00 AADO АА”, 
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/ [25] */ 

$^FF00 FFOO FFOO ҒҒ”, 
/* (26) */ 

$1122 4488 1122 4488", 
/* (271 */ 

$^FF00 0000 ҒҒ”, 

/* (28) */ 

%%0102 0408 1020 4080", 
/* 1291 */ 

$^^A00 8000 8800 80", 
/* (30] */ 

$^FF80 8080 8080 8080", 
/ 131] */ 

$"081C 22C1 8001 0204", 
/ 132] */ 

$25814 2241 8800 АА”, 
/ (331 */ 

$^40A0 0000 040A", 

/ 134] */ 

$^0384 4830 0С02 0101", 
/* (35) */ ҘГ 

$^8080 413E 0808 МЕЗ", 
/* 1361 */ 

$^1020 544A ҒҒ02 0408", 
/* (37) */ 

$^5000 0000 08", 

/* 138] %/ 

$^50", 

/ [391 */ 

$^0002 4000 0000 0080", 
/* (40) */ 

%%0002 4000 0000 0880", 
/* (411 */ 

$^5000 1000 8002 0020", 
/% 1421 */ 

4,8002 0010 8002 0010", 
/* (431 */ 

$^0092 0000 9200 0092", 
/* (441 */ 

$"0092 0008 8220 0092", 
/ 1451 */ 

%%0092 0028 8228 0092", 
/ (46] */ 

$^1082 1082 1082 1082", 
/* (47) */ 

$^2288 2288 2288 2288", 
/ (48] */ 

$2288 22А8 2288 2288", 
/* (401 */ 

$^2288 22A8 2288 2А88", 
/ 1501 */ 

$°228А 22A8 2288 2A88", 
/* (51) */ 

$^228A 22А8 2288 AA88", 
/* 1521 */ 

$^228A A2A8 2288 AABB", 
/* [53] */ 

$^228A AAAS 2288 AAAB", 
/* (54) */ 

$^228A AAAS 228A AAAB", 
/* (551 */ 

$7AA11 АА45 АА11 M54", 
/* (56) */ 

$7AA51 АА45 АА11 АА55", 
/* (57) */ 

$^AA55 АА45 АА55 АА54", 
/% (581 */ 

%”АА55 АА45 АА55 АА55", 
/* 159] */ 

%”АА55 АА55 АА55 АА55", 


/% (621 %/ 
%”АА55 BASS АА55 AB75", 
/* (631 %/ 
%ЕЕ55 BASS ЕА55 АВ55", 
/% 164] */ 
$°EE55 ВА55 ЕЕ55 АВ55", 
/* (65) */ 
%”ЕЕ55 ВА55 ЕЕ55 ВВ55", 
/% (661 %/ 
$'EE55 8855 ЕЕ55 ВВ55", 
/% (67) */ 
%”ЕЕ55 BB55 EESD ВВ55", 
/% (681 */ 
%”ЕЕ55 8855 EESD FB55", 
/% (691 */ 
$°EE55 ҒВ55 EESD ҒВ55", 
/* (101 */ 
%”ЕЕ55 ҒҒ55 ЕЕ55 FF55", 
/* (71) */ 
$°FF55 FF55 FF55 FF55", 
/% (72) */ 
$°FF55 FF5D ҒҒ55 FF55", 
/* [731 */ 
$°FF55 FF5D ЕҒ55 FFD5", 
/* {741 */ 
$^FF55 FFDD FF55 FFD5", 
/* [751 */ 
$°FF55 FFDD FF55 FFDD’, 
/* [761 */ 
%”ҒҒ5Т FF5D FF75 FFD5", 
/* UT) */ 
$°FF57 FF7D FF7D ЕРОТ", 
/* (78) */ 
$°FFDD FFFF FFF7 ЕЕТЕ”, 
/% (791 */ 
$^FFDF FFFF FFF7 FFTF*, 
/% (801 */ 
ФӨЕҒЕҒ FFF7 FFFF FFTF*, 
/% (81) */ 
$°FFFF FFFF FFFF FFTF*, 
/% (821 */ 
$^FFFF FFFF FFFF FFFF^, 
/* (83) */ 
$°7FBF DFBF 6BDD 8078”, 
/* (841 */ 
$^FF03 0509 1121 4181", 
/* (851 */ 
$°ЕЕВЗ 4529 1129 4583", 
/* (86) */ 
$°FF93 5539 FF39 5593", 
/* (87) */ 
$°FE93 5539 EF39 5593", 
/* [88] */ 
$'FE93 1139 EF39 1193", 
/* (89) */ 
$'1010 1038 EF38 1010", 
/% (90) */ 
$^1192 5438 EF38 5492", 
/* [911 */ 
%1192 5438 EF38 5492", 
/* (921 */ 
$°55AA 55BA GDBA 55АА”, 
/* (93) */ 
%5ҒА9 51A3 458A SSAA’, 
/* (941 */ 
%”55ЕА 70А6 658E 57AA*, 
/% (951 */ 
%55АА 4182 4182 55АА”, 
/* (961 */ 
%”4бАб FFFF 4686 57AE^ 


/% (601 */ ) 

%”АА55 ВА55 АА55 АА55", /** Extra bytes follow.. */ 
/* (61) */ / $^0000 0034 0001 1400" 
$”AA55 ВА55 АА55 АВ55", }; 
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Basic School 
Dialog Events in ZBasic 


DIALOG MANIA 


The word 'mania' as used in the title 
of this month's Basic column has a kind 
of dual meaning. My dictionary says 
that 'mania means: 1. wild or violent 
mental disorder 2. an excessive enthu- 
siasm; obsession. I find both definitions 
express what it is like to program with 
ZBasic. Many of you have been follow- 
ing the 'Basic Wars' as they have been 
progressing. MS Basic 3.0 has been 
announced as of the writing of this col- 
umn, although I have not seen it yet. 
This is supposed to be a $25 upgrade. 
The MS Basic compiler is also supposed 
to be out, at least Microsoft is marketing 
it by direct mail. (Note: The MS Basic 
compiler and version 3.0 of the MS 


Basic interpreter are two different products, both of which you 
need to compile programs!) Pterodactyl Software's PCMacBa- 
sic has not come back off the drawing board and True Basic is no 
better off than when I reviewed it back in August. But there has 
still been some hope. Zedcor has been scrambling to fix bugs in 
ZBasic and release version 3.02. They are to be commended for 
their dedication to making their product a success. 

Why do I say that both definitions of 'mania' describe 
programming with ZBasic? The second definition comes to 
mind first. I'm excited to see the big improvements that have 
been incorporated into ZBasic. In fact, the BOMB is a much less 
frequent sight. In fact, the BOMBs that appear from time to time 
now are more obscure. In fact, some of the BOMBs are 'self 
inflicted'. In other words, sometimes things that I am not doing 
correctly turn out to be the problem. But there have been a few 
problems that demonstrate that not all the problems have been 
removed from the compiler. 

One such example of what I am talking about was brought 
to my attention by one of our subscribers from Switzerland. He 
summed up ZBasic nicely when he said "...ZBasic is really a 
great Basic if only it worked!" He described to me a problem 
he was having when working with DIALOGs and ZBasic. He 
stated that he could not "flush the value of the DIALOG(1) 
function". Theanswerto his problem turns out to not be too hard, 
however, it reveals to us some other difficulties that ZBasic has 
‘built in’ to it. 

First, the solution to the DIALOG(1) problem is that it is not 
a problem. It will be helpful to understand how the DIALOG 


M Button clicked : 
И Edit Field : 

E Inactive Window : 
EI Closed Window : 

B Erased Window : 
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" é File 


Dave Kelly 
MacTutor Vol. 3 No. 1 


Dialog Event t 


Return press : 
Tab press : 


ASCII key pressed : 


DIRLOGCOS : 
Active Window 8 2 


Current Edit Field: Output Window ® 3 


functions operate. The DIALOG function originates with MS 
Basic. The excitement comes when I see all the enhancements 
that have been added to the ZBasic implementation of DIALOGs. 
The purpose of the DIALOG function is to inform us when events 
(such as BUTTON, EDIT FIELD and WINDOWS) that occur 
between the DIALOG ON and DIALOG OFF statements. 

It is important, when using DIALOG functions, to know 
when the function data is valid. The DIALOG(0) function is the 
key to it all. When an event occurs, the DIALOG functions are 
stored up in a 64 event queue. The ON DIALOG GOSUB 
statement is supposed to cause an interrupt to occur when some 
kind of event has happened. I say it is'supposed to' because when 
writing the sample program included here found that some of the 
itemsin the queue were notautomatically read until anotherevent 
occurred. Of course the new event was then pushed onto the 
queue and would not automatically interrupt via ON DIALOG. 
My solution was to poll the event queue continuously unless it 
was empty by accessing the DIALOG(0) function. Anyway, 
ideally the ON DIALOG should notify the program whenever 
any DIALOG events occur. The are seven events that are 
common to ZBasic and MS Basic. ZBasic now has 16 DIALOG 
functions including functions which support the Zoom windows 
and keyboard events. The DIALOG(0) function will return а 
number 1-16 (1-7 in MS BASIC) which will indicate to you what 
kind of event occurred. At the same time, the function that 
coresponds to ће DIALOG(O0) result will be updated. The 
functions ( DIALOG (1-16) ) are ONLY valid just after the 
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DIALOG(0) function returns an event of that type. Otherwise the 
last event of that type remains on, stored up in the DIALOG 
functions. The figure shows a flow chart of what happens when 
DIALOG(0) has an event to be processed. Just remember to poll 
DIALOG(0) first to find out which of the other functions you will 
need to poll next. 


=0 ; DIALOG(0) 


DIALOG(0) 


Figure 2 


Another phenomenon that was observed was that when 
events are active ( the lines between DIALOG ON, MENU ON, 
BREAK ON, MOUSE ON and DIALOG OFF, MENU OFF, 
BREAK OFF, MOUSE OFF) the program seems to run much 
slower than without events on. I tried to turn off events wherever 
possible with some increase in speed, but there seems to be some 
delay between polling the time an event occurs and when it is 
finally processed. Has anyone done any benchmarks to compare 
speed when events are turned on? Itis a difficult thing tocompare 
as the implementation varies so much from one language to 
another. 

Look out here comes another bug... As it turns out, the 
DIALOG(8) and DIALOG(9) statements work great. The prob- 
lem is that Zoom windows still don't work quite right. In ZBasic 
3.02 the demo program below will BOMB if Zoom windows are 
made active. I have set itup to demonstrate how it should work. 
The PEEK (&28E) AND 128 statement towards the beginning of 
the program checks to see if the Mac has old 64K ROMS or the 
new 128K ROMS installed. If the new ROMS are available then 
the window type should be set to 9 when the windows are created. 

The example program outlines the basic flow which you 
will want to use when you implement your own ZBasic event 
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-5 ; DIALOG(5) valid 
-6 ; DIALOG(6) valid 
-7 ;DIALOG(7) valid 
-8 ; DIALOG(8) valid 


loops. Notice that Menu events and Dialog events are mixed in 
the same event loop. This same structure also applies for MS 
BASIC. Any questions? 


REM ZBasic V3.02 Dialog Example 
REM ©MacTutor 1987 
REM By Dave Kelly 


No Event 

most recently pressed Button 

most recently selected Edit Field 

most recently selected Inactive window 
most recently selected window with Go-away selected 
Window needs refreshing 

Return key in Edit Field or Button 

Tab key in Edit Field 

Window with Zoom in selected 
Window with Zoom out selected 
Shift-Tab key in Edit Field 

Clear key in Edit Field 

Left Arrow in Edit Field 

Right Arrow in Edit Field 

Up Arrow in Edit Field 

Down Arrow in Edit Field 

most recently press key (ASCII) 


WINDOW OFF:REM Always use this as first line of program 
to prevent default window from being created 
COORDINATE WINDOW:REM Set window to 
tosh coordinate system 

False=0:True=NOT False 

IF PEEK(&28E) AND 128 THEN Wtype=1 ELSE Wtype=9 
Wtype=1:REM Due to Bugs in ZBasic 3.02 Zoom window 
will not be used. 


Macin- 


MENU 1,0,1,"File" 

MENU 1,1,1,"Quit" 

DIALOG OFF 

WINDOW 1,"Window 1",(10,50)-(250,200), Wtype 
TEXT 4,9,0,0 

BUTTON 1,1,"Button 1",(20,20)-(100,50) 
BUTTON 2,1,"Button 2”,(20,60)-(100,90) 
WINDOW 2,"Window 2",(275,50)-(500,200), Wtype 
TEXT 4,9,0,0 

EDIT FIELD 1,°",(10,10)-(100,35),1,1 

EDIT FIELD 2,”",(10,40)-(100,65), 1,1 

WINDOW 3,"Dialog Event (Window #3)", 
(500,340),28 

TEXT 4,9,0,0 


(10,250)- 
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ON DIALOG GOSUB "DialogEvent" 
ON BREAK  GOSUB "BreakEvent" 
ON MENU GOSUB "MenuEvent" 
DIALOG ON:BREAK ON:MENU ON 
"Mainloop”:DO:D=DIALOG(0) 

IF 00 THEN GOSUB "DEvent" 
UNTIL D=0 

GOTO "Mainloop" 


"MenuEvent" 

DIALOG STOP: 
Menunumber=MENU(0):ltemnumber=MENU(1) 

IF Menunumber=1 AND itemnumbers1 THEN END 
DIALOG ON 

RETURN 

"BreakEvent" 

STOP 


"DialogEvent" 

D = DIALOG(0):REM check to see what event occured 
"DEvent" 

DIALOG STOP 

Currentwindow = WINDOW(0) 

Windowselection = WINDOW(1) 

WINDOW OUTPUT 3 

IF D = 1 GOSUB "Buttonevent" 

IF D = 2 GOSUB "EditEvent" 

IF D = 3 GOSUB "InactiveWindow" 

IF D « 4 GOSUB "Closebox" 

IF D = 5 GOSUB "Refresh" 

IF D = 6 GOSUB "Returnkey" 

IF D = 7 GOSUB "Tabkey" 

IF D = 8 GOSUB "2оотіп" 

IF D = 9 GOSUB "Zoomout" 

IF D 10 GOSUB "Shifttab" 

IF D 2:11 GOSUB "Clearkey" 

IF D 212 GOSUB "LeftArrow" 

IF D 213 GOSUB "RightArrow" 

IF D «14 GOSUB "UpArrow" 

IF D «15 GOSUB "DownArrow" 

IF D =16 GOSUB "Keypress" 

PRINT @(50,3) "DIALOG(O) : "р 

PRINT @(50,4) "Active Window #";Currentwindow 
PRINT @(50,5) "Output Window #";Windowselection 


WINDOW OUTPUT Outwindow: WINDOW Windowselection 


DIALOG ON 
RETURN 


"Buttonevent" 
Buttonclicked=DIALOG(1) 


Bstatus- BUTTON(Buttonclicked):BUTTON Buttonclicked,3- 


Bstatus 
PRINT@(1,1) "Button clicked: ";Buttonclicked 
RETURN 


"EditEvent": 
EditField=DIALOG(2) 
PRINT@(1,2) "Edit Field : 
RETURN 
"InactiveWindow" 


";EditField 
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Windowselection=DIALOG(3) 

PRINT@(1,3) "Inactive Window : ";Windowselection 
RETURN 

"Closebox": 
ClosedWindow=DIALOG(4) 

IF ClosedWindow=3 THEN END 
PRINT@(1,4) "Closed Window : 
RETURN 

"Refresh": 
ErasedWindow=DIALOG(5) 
PRINT @(1,5) "Erased Window : 
RETURN 

"Returnkey”: 
Returnpress=DIALOG(6) 

PRINT @(25,1) "Return press: °;Returnpress 
RETURN 

"Tabkey": 
Tabpress=DIALOG(7) 
PRINT @(25,2) "Tab press : 
RETURN 


":ClosedWindow 


"-ErasedWindow 


"; Tabpress 


"Zoomin": REM NEW ROMS ONLY 

Zin=DIALOG(8) 

WINDOW Zin 

PRINT@(1,1) "Thank you for zooming in window";Zin 
PRINT @(25,3) "Zoom in window: ";Zin 

RETURN 

"Zoomout": 

Zout=DIALOG(9) 

WINDOW Zout 

PRINT@(1,1)"Thank you for zooming out window";Zout 
PRINT @(25,4) "Zoom out window : ";Zout 

RETURN 

"Shifttab": 

CurrentEditzDIALOG(10) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 

"Clearkey": 

CurrentEdit-DIALOG(11) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 


"LeftArrow": 

CurrentEdit-DIALOG(12) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 

"RightArrow": 

CurrentEdit-DIALOG(13) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 

"UpArrow": 

CurrentEditZDIALOG(14) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 

"DownArrow": 

CurrentEditZDIALOG(15) 

PRINT @(25,5) "Current Edit Field:";CurrentEdit 
RETURN 
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Basic School 
Basic Wars... the Sequel! 


This episode of Basic Wars finds us look- 
ing at the newly released Microsoft Basic 
Compiler (version 1.0) and MS Basic Inter- 
preter (version 3.0). In the first episode several 
months back we were introduced to several of 
the newcomers to Basic programming on the 
Macintosh. I refer you to the August 1986 
MacTutor Basic column entitled "And then 
came... Basic Wars!" for an introduction to 
ZBasic, True Basic, and PCMacBasic. Of these 
three, ZBasic now appears to be leading the race. 
If you have been following the Basic Wars Saga, 
you know of the major improvements in the 
reliability of ZBasic. It has come a long ways 
from the frequent bombs to the fairly reliable 


product we see now. Finally after along wait (and some pressure 
from competition like ZBasic) Microsoft has recently released 
version 3.0 of the MS Basic Interpreter and version 1.0 ofthe new 
Microsoft Basic Compiler. 


Basic 3.0 Improvements 


Before the battle begins, we should discuss the MS Basic 
Interpreter, version 3.0. By now most of you have heard about 
the improvements that have been made and registered owners 
have had a chance to upgrade for $25 (Well worth $25, I might 
add). MS Basic Interpreter is still a very reliable product just as 
before with major enhancements (i.e. value added). To begin, 
here is a brief overview of some of the new features: 

First and very importantly, Microsoft has now bundled the 
CLR ToolLib Library with the interpreter. This alone is worth 
the $25 to upgrade from earlier versions, especially if you didn't 
already have CLR ToolLib. There are some new and improved 
toolbox calls included which were not in the original CLR 
ToolLib. Among those that were added to the original CLR 
ToolLib are: 


BringToFront CmdKey DisposeDialog 
GetDialogBut GetDialogText GetMouse 
GetNewDialog ModalDialog PtinRects 
RealFont SetArray SetCreate 
SetDialogBut SetDialogText SetitemStyle 
SetOrigin SetWindowPic SetWTitle 
SubPt 


The list above is fairly complete unless I missed adding 
something to the list. One great advantage is that now the library 
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BASIC Compiler 


OA - Use Long Addressing 
[]C - Check Array Boundaries 
00 - Compile for Decimal Math [А - Link Run-time 
ПЕ- Generate Errors List 
C) I - List Include Statements 


Dave Kelly 

MacTutor Editorial Board 
General Dynamics Corp. 
MacTutor Vol. 3 No.2 


орца са 


Compile end Execute 


O L- Generate Full List 
DN - Process Run-time Events 


[]S - Generate Symbol File 
[]U - Default Arrays to STATIC 


Fig. 1 MS Compiler Options Dialog 


calls provided will be more widely used. Previously only those 
who puchased the CLR Libraries could take advantage of them. 
This limited the type of programs which could be widely distrib- 
uted to those that could be written without CLR Libraries. I 
expect that we will be seeing more widespread use of the 
Libraries now that they are part of the interpreter package. 
(NOTE: ZBasic claims to have more Toolbox calls available, but 
some if not most of them are still not compatible with other 
ZBasic calls. Example: INSERTRES MENU is not compatible 
with ZBasic MENU statement. However, INSERTRESMENU is 
notavailable with the MS Basic Libraries. Maybe CLR will write 
some more for us!! The MS ToolLib routines are compatible 
with al] MS Basic commands). 

The long awaited HFS incompatibility has been corrected 
with version 3.0. The FILES§$ statement now returns the full 
pathname for HFS files (MFS is not changed). In version 2.x the 
FILES$ statement would only return the full pathname for a file 
in the root directory. This problem has been corrected with 
version 3.0. A new Basic statement has been added - CHDIR. 
CHDIR changes the current default directory to one specified 
with the statement. Using CHDIR is similar to setting the 
PREFIX command in ProDos on the Apple ][ series computers or 
using 'cd' on а UNIX™ operating system. (NOTE: no equivalent 
in ZBasic). Also notice that since the Scrapbook DA uses the 
default disk, the Scrapbook file that can be accessed will change 
when the CHDIR statement is used. Problems with single voice 
sound and the new ROM's has been fixed with version 3.0. 

Now up to six windows can be opened at the same time. 
Older versions of the interpreter only allowed 4 windows open. 
(Note: ZBasic also allows up to six windows open). WIN- 
DOW(6) now returns the handle for the active edit field in the 
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current output window. WINDOW (6) returns zero if the win- 
dow has no active edit field. This function is useful with some 
toolbox functions. 

The EDIT FIELD statement has been enhanced to include 
the type values 5,6,7 and 8. These types correspond to the types 
1,2,3 and4 except that the default text in the EDIT FIELD is not 
highlighted. This will be useful in programming a text editor 
application ( read on for more statements to make this possible). 

Multi-line IF/THEN/ELSE statements are now allowed. 
Use of multi-line IF/THEN/ELSE improves readability of your 
program and fewer program lines are required in many cases. For 
better program structure, the multi-line IF/THEN/ELSE state- 
ment makes it easier to avoid the use of GOTO (a no-no if you 
are following good programming techniques). ZBasic provides 
multi-line IF/THEN/ELSE via use of the LONG IF/XELSE 
statement. MS Basic 3.0 uses the following IF/THEN/ELSE 
structure: 


IF condition THEN 

statement [statement ] 
ELSEIF condition THEN 

statement [statement ] 
ELSE 

statement [statement ] 
END IF 


While ZBasic multi-line IF/THEN/ELSE statements are 

i as the MS Basic implementation, it should 
be noted that the MS Basic syntax follows a more traditional 
implementation (as done in other languages). The MS Basic 
implementation is compatible with the ANSI (American Na- 
tional Standards Institute) Basic implementation. 

The new function SADD returns the address of the first byte 
of data in a string expression. This will typically be used to pass 
the address of a string to a machine-language routine. [Since the 
first byte of a Macintosh Pascal string is the length byte, getting 
to the first character is a bit of a pain. This function is a nice 
addition. -Ed.] 

Improvements have been made to Apple LaserWriter and 
LaserWriter Plus support. Printer support was lacking in previ- 
ous versions of MS Basic. I have not verified exactly what 
improvements have been made. I will reserve that subject for a 
future issue of MacTutor. 

The Basic runtime interpreter package is now bundled with 
the full interpreter for distributing your programs to others that 
don't have the interpreter without paying any runtime fees or 
licenses. The interpreter routines are the same, but the runtime 
package has no editor and no way to change your program. 

Other than what I have just mentioned, there are no other 
documented changes. Itis apparent that there are some improve- 
ments that are not documented. One such improvement is found 
in an example named 'DOUBLE CLICK ME' on the MS Basic 
disk 1 (there are two disks now, one for Basic and one for the 
ToolLib stuff). Itis also found in a program named 'QnD' on the 
compiler Toolbox disk. 'OnD' stands for ‘Quick and Dirty'. MS 
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has provided us with a quick and dirty editor program written in 
Basic. Until now a text editor could not be written with either MS 
Basic or ZBasic. Several new statements show up in boldface in 
the program: 


TECALTEXT WINDOW(6) 

TEUPDATE VARPTR('C(0)), WINDOW(6) 
TESCROLL oFirstCh*-10,oFirstLn*-16, WINDOW(6) 
TEACTIVATE WINDOW(6) 


Also found on the MS Basic Interpreter disk in a demo file 
also named DOUBLE CLICK МЕ: 


TESETTEXT SADD(OldEdit$), LEN(OldEdit$), WINDOW(6) 
TEUPDATE VARPTR(rC(0)), WINDOW(6) 


Since these statements are in boldface it follows that they 
are a part of the reserved words built into Basic. It is exciting to 
find out that they exist because they fill a void. Text editing has 
been limited in Basic. At the present time I don't have any 
information on the proper use of these statements, but Microsoft 
has promised to send me information which I can pass on to you. 
I suggest that if you want to try to use them before you have 
documentation that you do so with caution. I will bring you more 
information on how to use these statements in a future issue as 
Soon as I can get the information from Microsoft on them. 
(NOTE: these are also supported by the MS Compiler too!). 


MS Basic Compiler Unvelled 


Finally after months of rumors the MS Basic Compiler has 
been officially released. Of the compiled basic products now 
available this one is number one for compatibility with the MS 
Basic interpreter. There are a few small modifications that may 
be needed in some programs, but most programs will not require 
any modification. Compiled programs will likely run up to 10 
times faster than the interpreter. Note how similar the options 
dialog in fig. 1 is to MacFortran. This is because Absoft wrote 
the compiler. We may find many more similarities between these 
two compilers in time. The additions and enhancements to the 
interpreter version 3.0 are all supported by the compiler includ- 
ing the Toolbox libraries. The same CLR ToolLib which is 
included with the interpreter is also included with the compiler. 
It should be noted here that any other libraries from CLR or others 
you may have written for the interpreter are supported equally 
well by the compiler. The compiler does not support calls to 
routines written in other languages unless they follow the guide- 
lines setup in "Building Machine Language Libraries". There 
are a few differences in the BASIC language provided by the 
interpreter and the compiler. One additional statement (not 
supported by the interpreter) is the SELECT...CASE construct. 
SELECT...CASE is a useful statement which is supported by 
the ANSI (American National Standards Institute) standard for 
Basic (also supported by True Basic and many other languages). 

With the compiler you may declare your arrays to be static 
or dynamic. Dynamic arrays can be erased and redimensioned 
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during runtime. Static arrays are set up at compile time and 
cannot be redimensioned during runtime. All definitions of 
functions and declaration of variables should appear at the 
beginning (orclose to the beginning) of your compiled program. 
For example if a function defined by using a GOSUB at the 
beginning of your program and the subroutine with the function 
definition appears sequentially later in the program than the first 
line where the function is called, the compiled program will not 
work properly. The solution is to define the function and 
dimension arrays early in the program and avoid setting up 
functions and dimensions in subroutines. 

Compiled subprograms may be called recursively. This 
allows subprograms to call themselves. Programs written for the 
MS Basic interpreter will not work recursively. An example is 
the mathematical factorial function where N! 2 1*2*3...*N. A 
sample subprogram would be the following: 


SUB fact (x, result) 
IF x = 1 THEN 
result » 1 
ELSE 
CALL fact(x-1,newresult) 
result « x * newresult 
END IF 
END SUB 


Most interpreter programs you will find will compile with 
no modifications. And best of all... they still work as expected. 
This is not true if you try to convert MS Basic programs to 
ZBasic. The structure is very similar, but not all the commands 
work exactly the same way that the MS Basic interpreter and 
compiler does. 

Before we gettoo far ahead of ourselves in talking about the 
compiler, it should be noted that the compiler should be thought 
of as a stand alone package. In other words, although it is 
compatible with the interpreter, the interpreter is NOT required 
to write and compile programs. The Apple EDIT program 
(version 2.0) is included with the compiler. Actually any editor 
program will work. It just so happens that it is convenient to use 
the interpreter's editor if you have both the interpreter and 
compiler. This way you can run your program (provided you 
understand the few differances between the interpreter and the 
compiler) with the interpreter until it is debugged. Then when 
your program runs like you want it to, you may then save the 
program as TEXT and run the compiler. Both the compler and 
the interpreter have added a Transfer... item in the File menu for 
transferring from one application to another (in this case from the 
interpreter to the compiler). You could transfer to and from the 
EDIT application to compiler equally as well. It should be noted 
that the last line of a program saved by EDIT is lost when read in 
by the interpreter. So BEWARE. Idon't know which is at fault, 
interpreter editor or EDIT program (I think it is the interpreter 
editor but I don't know for sure), but it is not hard to work around 
this bug. 

Two methods may be used in compiling your programs. A 
set of runtime files (called runtime overlays) may be attached to 
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your application at compile time to create a full double-clickable 
standalone application. Or you can compile just the program or 
set of programs (via a compiler list) and use the runtime files 
separately. This method will save space ona disk where you have 
several compiled programs. This way the runtime stuff will only 
havetobeon the disk once. ICONS and otherresources will have 
to be added separately with ResEdit. 

A few compiler metacommands are provided that may be 
imbedded in the text of your program. Imbedding the metacom- 
mands in your program is helpful for ignoring text that should not 
be compiled or including text that should not be used when 
running the interpreter. The metacommands are imbedded in 
remark statements (which are ignored by the interpreter because 
they are comments). For example, the Search, Run and Windows 
menus of the interpreter are normally disabled in an interpreted 
program by a few lines of code similar to this: 


FOR i = 3 TO 5 : MENU i,0,0,"" : NEXT i 


This statement leaves 3 blank menus in place of the inter- 
preter menus. In the compiler, these menus are not used and don't 
need to be erased (because they aren't there). In this case you may 
want to use the compiler metacommand: '$SIGNORE ON before 
the statement to erase the menus and use '$IGNORE OFF to 
resume compiling. By doing this, the compiled version or your 
program will not have include three blank menus as the inter- 
preted version does. The metacommands that are available are: 

$INCLUDE to compile a file (stored on disk) and insert that 
file at the point where the $INCLUDE metacommand is used. 

$IGNORE ON instructs the compiler to ignore source lines 
until it encouters ап $IGNORE OFF. 

$OPTION is used to change the compiler options that may 
be set before compilation. $OPTION allows any of the options 
to be changed during compilation. The options may be selected 
from a dialog box (see figure 1) before compilation. The 
program execution speed is affected by the options you choose. 
For example if you don't select 'C' for checking array boundaries, 
the error checking code will not be included in the compiled 
program and the program will run faster. 

$PAGE can be used to set page breaks in compiler listing 
files. 

COMPILER HANGUPS 


There are only a few things that have not been up to snuff for 
creating professional Macintosh applications with the MS Basic 
Compiler. First, there is no compiler option or statement to 
disable the default window and default menus. If you recall, this 
was one of my complaints early on in the release of ZBasic. 
ZBasic has fixed that oversight by adding the WINDOW OFF 
statement. 

There are a few minor bugs which affect only a few things 
you may want to do, and even then you can program around them 
with other statements. For example, I found that when compiling 
my Clipping Region Demo from last March 1986 that the 
compiled version did not run the same. It turns out that the CLS 
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BENCHMARK М5 BASIC 3.0 (0) MS BASIC 3.0 (d) MS Compiler (b) MS Compilgredk or 
ZBasic 

SIEVElInteger Array 

Dynamic 667 672 56 56 na: NOTE-1 
Static na na 10 (10) 10 (10) 7 (7) 

SIEVE FloatingPt. Array 

Dynamic 733 792 58 63 na: NOTE-1 
Static na na 13 17 75 (73) 

FOR Loop Integer 7 7 1 (1) 1 (1) 1 (<1) 

FOR Loop Real 15 18 3 (3) 9 (9) 15 (26) 

Array Lookup Integer 

Dynamic 83 86 17 17 na: NOTE-1 
Static na na 1 (1) 1 (1) 1 (1) 

Array Lookup Real 

Dynamic 85 87 19 20 na: NOTE-1 
Static na na 1 (1) 1 (1) 18 (18) 

Math Operations 

Addition 100 102 1 (1) 1 (<1) 51 (48) 
Subtraction 102 110 1 (1) 1 (<1) 58 (55) 

Multiply 100 204 1 (s1) 1 (s1) 211 (208) 
Division 107 205 1 (1) 1 (<1) 488 (486) 
String Operations 

Concatenation 63 63 39 (39) 39 (39) 10 (10): NOTE-2 
Pattern Match 42 44 30 (30) 31 (31) 6 (6): NOTE-2 
Graphics 

Line (BASIC stmt) 23 23 10 (7) 10 (7) 16 (6): NOTE-3 
Line (ROM call) 18 18 5 (5) 5 (4) 5 (5) 

Diagonal Line 39 39 30 (15) 31 (15) 34 (15): NOTE-3 
CIRCLE 38 38 38 (19) 38 (20) 38 (19): NOTE-4 
Set Pixel (PSET) 82 82 52 (39) 52 (40) 56 (32): NOTE-5 
FILE I/O (data written/read on 400K floppy) 

Random PUT 61 61 44 (25) 44 (29) WNR (114) 
Random GET 43 41 27 (14) 28 (14) WNR (8) 
Sequential PRINT# 24 25 5 (4) 5 (4) 12 (9) 
Sequential INPUT 13 13 3 (3) 3 (3) Crashed (Crashed) 


NOTES: 

WNR: Would Not Run (A few minor modifications by MacTutor allowed these routines to run. Times in parenthesis). 

1) Sinse ZBasic does not support ERASE or REDIM, it was assumed that they consider ALL arrays to be static. 

2) 2Ваѕіс string variables are limited t 255 characters. MS Basic strings сап be up to 32,767 characters. 

3) ZBasic does not implement a LINE statement within the language. The ZBasic equivalent statement is PLOT. Since 
ZBasic's default coordinate system is 1024 X 768 and MS Basic's is 512 X 320, а COORDINATE WINDOW statement 
was included in the benchmark's source code to make all ZBasic graphics operations based on 512 X 320 pixels. 

4) ZBasichas aslightly different implementation of the CIRCLE statement. Since ZBasic's default coordinate systemis 1024 
X768 and MS Basic's is 512 X 320, a COORDINATE WINDOW statement was included in the benchmark's source code 
to make all ZBasic graphics operations based on 512 X 320 pixels. 

5) ZBasic does not have a PSET statement. The ZBasic equivalent is PLOT. Since ZBasic's default coordinate system 
is 1024X 768 and MS Basic'sis512 X320, a COORDINATE WINDOW statement was included inthe benchmark's source 


code to make all ZBasic graphics operations based on 512 X 320 pixels. 

The benchmark presented for sequential file /O does 5000 writes and 5000 reads from a sequential file. The benchmark 
presented for random file I/O does 5000 PUTs and 5000 GETs from a sequential file. The math benchmarks presented do 
100,000 iterations of each of the four standard math functions in single-precision format. The string operations presented 
were performed 30,000 times each. 

All the benchmarks above were performed by Microsoft on a 512K Macintosh, Finder 5.3, System 3.2, and HyperDrive 
20. Benchmark results by MacTutor (those inside parenthesis) were performed on a Macintosh Plus, Finder 5.3, System 
3.2 and ProApp 40. 

The benchmarks can be obtained by contacting Microsoft Corporation, Public Relations, 16011 NE 36th Way,Box 97017, 
Redmond, WA 98073-9717 (206) 882-8088 and asking for the Microsoft BASIC for Apple Macintosh Benchmark disk. 


Fig. 2 Benchmarks for the new MS Basic Compiler 
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statement mustreset the clipping region to the full screen because 
the second clipping region in the demo is cleared by CLS and the 
next items printed are not clipped. The solution is to select the 
clipping region again after the CLS statement or else not use the 
CLS statementatall. Since the fix for this problem requires only 
one extra statement (one that has already been used prior to the 
CLS statement), I don't consider this a major problem. Microsoft 
tells me that any bugs that may turn up in the compiler will be 
corrected in the next update to the compiler which could be as 
early as the end of March (22). I would hope that Microsoft will 
be as quick to respond to problems as Zedcor has done with 
ZBasic. Of course, I think that ZBasic had many more problems 
as evidenced by all the system bombs that we had all experienced. 
If Microsoft is responsive to what the users need (as Zedcor has 
been), then I see no reason why the MS Compiler won't be a 
Success. 

Another hangup is the way the compiler must have the Basic 
Overlays available in just the right folder. This also is something 
that you can work around because at least the compiler looks for 
the Overlays in the places you are most likely to put them. I would 
suggest the same sort of method that Lightspeed Pascal uses to 
find files when the compiler can't find them. When files can't be 
found, the GetFile dialog is displayed so the user can help find the 
file that is needed. If itis not done this way, I really don't feel that 
there is complete HFS compatiblilty. [This is a simple error 
trapping methodology. We fail to understand why it is not used 
by more programming languages. -Ed] 


THE BOTTOM LINE 


OK, you're probably wondering what's the bottom line. 
What product is the best? I'm not so sure that the dust has settled 
yet, but we can come to some conclusions now. For comparison, 
the benchmark tests form the August 1986 MacTutor have been 
executed for the MS Compiler. The interpreter results have not 
changed. The Sieve of Eratosthenes executed in 10 seconds for 
both binary and decimal compiled versions and static variables. 


ZBasic as you recall was 7 seconds (also uses static variables, 
dynamic not available in ZBasic). With dynamic variables the 
MS Compiler time was 56 seconds. In the same benchmark test 
done by Microsoft using floating point arrays (instead of integer 
arrays) the times were dramatically different. The MS Basic 
binary time was 13 sec., decimal time 17 sec. and ZBasic 75 
seconds (all using static arrays). I think that these results just go 
to show you that one benchmark test does not give conclusive 
results as to what is better. Sometimes the results are only 
measuring specific statements and don't represent the perform- 
ance real-world applications. 

The MacTutor benchmark used back in Aug. 1986 returns 
the same accuracy results as for the Basic interpreter. Only the 
decimal version got the right answer; the binary version rounded 
off. The decimal verision ran in 4 seconds, but the binary ran in 
1 second. In addition, if you use the RAM cache on the Mac Plus 
and run the binary version twice in a row, the second time it runs 
in less than 1 second (0 seconds is returned, but the TIMER 
statement doesn't return tenths of a second so I assume that the 
time was rounded to zero). 

MACTUTOR BENCHMARK (Aug 1986) 

decimal compile time = 12 sec. 

Result = 503.54380215, 1.23, in 4 seconds 

binary compile time = 11 sec. 

Result = 503.5436, 1.23001 in «1 second 

Sieve compile time: 13 seconds (other times below) 


Microsoft has provided results (performed by Microsoft) to 
other benchmark tests which offer other comparisons. I have 
verified most of the ZBasic and MS Compiler results (results are 


in parenthesis). The table shown in figure 2 indicates these 
results. 


It appears from the results that the MS Compiler does 
computations much faster, but ZBasic handles string manipula- 
tions much faster (keeping in mind note-2 of the table). If you are 
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€ rating system above is for comparison only. Rating system here does not relate to previous € rating found in Aug. 1986 MacTutor.Since all products have some 
areas they can improve and five és is considered perfect, five @ are very difficult to get. 


* BASIC Overlays used by compiler must be either in same folder as Compiler, in BASIC Overlays folder which is in same folder as Compiler or in same 


Folder as source being compiled. 


*PCMacBASIC has files that must be located in the same folder as the object code. Sometimes loses track of where files are. 
* True Basic DO programs are not found immediately, but program has a method of finding them. 
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now wondering if you should buy ZBasic or the MS Compiler 
you may now have a tough decision. For the price ZBasic has a 
lottooffer, butas faras being compatible with the MS Interpreter, 
the MS Compiler is the one. It looks like there are some speed 
advantages to the MS Compiler that may be a deciding factor for 
some of you. I have updated and modified the Basic Comparison 
Chart from the Aug. 1986 issue, shown in figure 3. (The apple 
rating shown compares each product relative to each other and 
has no relation to the previous chart in the Aug. 1986 MacTutor. 
Atthis time I feel that the MS Compiler has an edge over the other 
products due to its reliability (it works) and compatibility with 
the MS Basic Interpreter (ver. 3.0). Toolbox support is sufficient 
and user expandable (if you want to write your own libraries). 
The race is still very close, but this is the way I see it at the present 
time. More to come... see you next month. 


MS Compiler Bugs 


There are a few bugs that we assume will be fixed promptly 
in the next update of the MS Compiler. At least if Microsoft is 
responsive to their users I'm sure they will want to make the 
proper corrections where they apply. Some of the problems are: 


9 No compiler option is availble to disable the default 
window. This is undesirable when custom windows are used 
(most of us use them all the time). 


? There is no support for ZOOM windows. Thisisa feature 
of the 128K ROMS which many of us would like to use. Of 
course Microsoft prefers double-clicking on the title bar to zoom 
the window, but even that doesn't work with the MS Compiler. 
We fail to understand why all the new ROM routines have not 
been supported as yet! 


? The CLS statement changes the clipping region. This is 
noticable when using the SetClip toolbox call. There is no 
problem with this when using the Interpreter. NOTE: Now that 
the CLR libraries are included as part of the Interpreter and 
Compiler, it is assumed that Microsoft will support the toolbox 
by making statements compatible. It should be noted that there 
may be several things that don't work exactly the same as the 
Interpreter when using libraries as the libraries were originally 
written for the interpreter. Mostof these type of problems can be 
worked around without much inconvenience. It would be unrea- 
sonable to think that all of the differences have been found. 


° Commnications does not work properly. If you want to 
verify this just compile the 'terminal' program included with the 
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sample programs supplied with the Interpreter. You will find that 
characters are lost in the compiled version. I verified this by 
connecting a Mac+ with an Apple//e directly with the 
imagewriter cable. If you use communications these problems 
could be a real pain. 


? It has been reported to MacTutor that only the Apple 
printer drivers are supported. I don't have any non-Apple drivers 
so I could not verify this. 


? Printing to a printer with the Compiler does not work the 
same as with the Interpreter. For example 

OPEN "O",#1,"LPT1:" 

PRINT #1, TAB(10) USING "SHH HB" 777.7711 

CLOSE #1 

sends a single form feed to the printer and does not print the 
number. The interpreter tabs over 10 spaces and prints the 
number as expected. Also: 

OPEN "LPTI:PROMPT" FOR OUTPUT AS #1 

PRINT "";TAB(10);"HELLO WORLD" 

CLOSE #1 

ignores the TAB and prints HELLO WORLD at the left 
edge of the page. These problems can be overcome with other 
Statements, but we hope that Microsoft will pay attention to 
problems like this. It appears that anytime TAB is sent to the 
printer from a compiled Basic program, the TAB functions are 
ignored. TAB works properly when printing to the screen. It is 
interesting to note that the Absoft Fortran product also had a lot 
of problems with printing. We wonder if there is a connection. 


° The compiler does not seem to optimize code. Object code 
files are very large especially when Libraries are used. A solution 
when using Libraries is to use ResEdit to modify the names of the 
Library CODE resources to one character long and change 
program lines to match. Now when program is compiled fewer 
bytes are required to specify the library CODE resource. Keep 
in mind that this makes your source code harder to read. 


While these problems may seem small, I hope that Micro- 
soft will be responsive to correcting this bugs as quickly as 
Zedcor has been with ZBasic. Even with the problems mentioned 
here, it is my opinion that the MS Compiler is closer to being bug 
free than ZBasic. 


If you find any more bugs, please let us know. Also it 


wouldn't hurt to let Microsoft know. We will be doing the same 
with hopes that the bugs will be corrected. = 
бм 


ceu 
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Fun With A Mac 


Random MacArt in Basic 


Random МасАг is an MS Basic program which creates 
catchy modern art designs. Each design is unique and exciting 
with a general movement expressed. These designs can be 
created almost instantaneously and have many potential uses for 
decorating, entertainment, and experimentation. Figure 1 shows 


:a design created by Random MacArt. 


Using Random MacArt 


Random МасАг is an easy program to use. To create a 
design, press COMMAND R and watch the random designs 
appear; the computer screen will seem alive! Each design will 
finish on its own. After you have admired or printed the design, 
click the mouse button once and a fresh new design will appear. 
When you have created all the designs you want, you can save or 
print them. To save a design, type COMMAND SHIFT 3. This 
saves the screen. In order to print a design, make sure the printer 
is on, then type COMMAND SHIFT 4. This will print the active 
window. Stopping or listing the program follows the normal MS 
Basic conventions. 


How Random MacArt Works 


The program is simple to understand. We will begin with 
the first line and go through the program. RANDOMIZE TIMER 
bases random numbers according to the time on the Macintosh's 
internal clock. If you were to use this program again at exactly 
the same time that you had used it on a previous day, so that the 
clock reading was the same, the same design would be created. 
You will most likely never get the same design twice. 

DIM shows the highest number of elements in the array 
specified in the statement. In this program it is set to 10 for both 
x and y. The DIM statement is really not necessary here because 
a maximum value of 10 is always assumed for an otherwise 
unspecified subscript, but it is good practice to routinely use DIM 
statements. 

In order for designs to be created one after another without 
having to rerun the program each time, a loop is used. When the 
computer gets to the last line of the program, the statement 
GOTO loop instructs it to return to the line with the statement 
"loop". 

The WINDOW statement opens a window on the screen 
within which the design will be drawn. The window-ID, one in 
this case, specifies the window's identification number. The 
commas show that there is no title for this window. (If there had 
been, it would have been in quotes between the two commas.) 
The numbers in parentheses specify the window size. The x 
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Fig. 1 Our random art program in Basic 


values for this window are 10 and 502, and the y values are 26 and 
332. Following the comma, the number three indicates that the 
type of window desired is an one-line border window. 

Following the WINDOW statement is a FOR/NEXT loop 
that is used in determining ten random values of x and y, labeled 
as x(n) and y(n). The statements in the loop are executed with n 
increasing by one each cycle. RND(1) returns a random number 
in the range of Oto 1. For x, the random number is multiplied by 
440, and for y, by 254. INT converts the numbers into integers, 
and then two is added to each. These latter steps insure that the 
design is drawn within the window's border. NEXT n forms the 
loop. After ten iterations the loop is exited. 

Next, nested FOR/NEXT loops are used to create the design 
based on the array of random x(n), y(n) values generated previ- 
ously. 

The LINE statement draws a straignt line between the 
coordinates pairs (х(п-1)+5*4), (y(n-1)+s*4) and (x(n)+s*4), 
(y(n)+s*4). For example, with n=0 and 5-0 the statement 
becomes LINE (x(1),y(1))-(x(2),y(2)). NEXT n forms aloop so 
that the successive points will be connected. The LINE statement 
following NEXT n connects the last point with п=10 back to the 
first point with n21. 

Without the FOR/NEXT loop on s, the design would look 
flat and simple. On every pass through the s-loop an identical 
design is created with (x,y) points displaced four pixels away 
from the previous design. By the time the loop is completed the 
result consists of 13 superimposed designs. 

The WHILE/WEND loop allows the user to view the design 
until the mouse button is depressed. MOUSE(0) is the state of the 
mouse button, with MOUSE(0)=0 indicating that the button has 
not been clicked and MOUSE(0)=-1 indicating that it has been. 
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When the user clicks the mouse the WHILE statement will end 
withthe WEND. (WEND means WHILE end). The colonallows 
two separate statements to be entered on one line. The CLS line 
clears the screen and the last line returns to "loop" to start a new 
design. 


Possible Modifications To Improve Random 
MacArt 


When you have tried the program and printed out some 
intricate designs, the next step is to experiment. If you would like 
your designs to have more sides to make them appear even more 
complex, or smaller to make them appear simpler, the number of 
random numbers to be chosen can be changed. Remember that 
if you increase the number of random numbers to be used, the 
DIM statement must also be increased. If you would prefer a 
larger or smaller screen, the window size numbers in the paren- 
theses can be altered. Three other types of windows can be 
obtained by changing the number three after the parentheses to 
one, two, or four. Try altering the numbers which are multiplied 
and added to the random numbers. This will position your 
designs in different parts of the screen and make your designs 
larger or smaller. The distance between each line of your designs 
can be altered by changing the value the variable s is multiplied 
by. Tocreate more or less lines, change the value of the variable 


S. As you can see the possiblities of this program are endless! 
Have a good time and experiment freely to make the most 
interesting designs possible. Try running this under the new 
compiler and see if you can notice any speed improvements. 


RANDOMIZE TIMER 
DIM x(10),y(10) 


loop: 

WINDOW 1,,(10,26)-(502,332),3 

FOR п=1 TO 10 
X(N)=INT(RND(1)*440)+2 
y(n)=INT(RND(1)°254)+2 

NEXT n 


FOR s=0 TO 12 
FOR nz2 TO 10 
LINE (x(n-1)+s*4,y(n-1)+8*4)-(x(n)+s*4,y(n)+s*4) 
NEXT n 
LINE (x(10)+s*4,y(10)+s*4)-(x(1)+8*4,y(1)+s*4) 
NEXT s 


WHILE MOUSE(0)=0:WEND 
CLS 
GOTO loop 
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Basic School 
The 3-D Math Package 


Benchmark Wars 


Benchmarks are not always what they seem to 
be. If you recall, in February, MacTutor printed 
results from benchmark tests which Microsoft pro- 
vided to compare the MS Compiler 1.0 with ZBasic. 
To make a short story longer... some of the bench- 
marks do not provide a true realistic view of the 
capabilities of each product. As a matter of fact, 
Zedcor says that "several of the benchmark times 
Microsoft claims... they are grossly misleading 
and, in some cases, intentionally deceptive". Well, 
since you are such an intelligent audience, you may 
decide for yourself. 

The Microsoft benchmark for math opera- 
tions basically is as follows: 


FOR i% = 1 TO 10000 
FOR j% = 1 TO 10 
C = 1.2345 + 3.1415 
NEXT j% 
NEXT i% 


Itisinteresting to note that if the values used in 
the math are declared beforehand that the MS times 
are much slower. 

al=1.2345: bl=3.1415 

FOR i% = 1 TO 10000 

FOR j% = 1 TO 10 
c! = al (math) b! 
NEXT |% 
NEXT i96 


It appears that in the first benchmark the MS Compiler 
computes the variable to be assigned to c! at compile time, thus 
making this benchmark become a test to see how long it takes to 
assign a variable. When run, this explains why all the Microsoft 
results for math were 1 second. Since these benchmarks are 
supposed to check math operations the results are now invalid. It 
might be interesting for those of you that want to use the MS 
Compiler that your programs will run faster when you use actual 
numbers instead of variables in calculations. The math opera- 
tions in this case were not really done at runtime. The actual 
results (for the second benchmark) are given in the next figure. 


MS (b) MS (d) ZBasic 
Addition 14 sec 40 sec 52 sec 
Subtraction 13 sec 48 sec 64 sec 
Multiply 16 sec 249 sec 211 sec 
Division 39 sec 457 sec 446 sec 
378 
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Fig. 1 Output of our 2-d function demo 


Now that we are comparing like operations, it may be 
concluded then that ZBasic (BCD math) math is about the same 
speed as MS Basic (d) (SANE math) with more accuracy. MS 
Basic (b) is fastest but gets wrong answers. Also not previously 
mentioned before, if you use ZBasic's LONG INTEGER mode 
the times are much faster, but keep in mind that you have to keep 
track of all decimal points yourself. Since the MS Compiler 
doesn't have the LONG INTEGER mode it is impossible to 
compare it. 

Some notes on the integer FOR-NEXT loop benchmark 
(30,000 iterations). If the loop is modified to do 900,000 
iterations (impossible without LONG INTEGERS) then ZBasic 
comes out faster (10 sec). To simulate this we have the loop: 


FOR j = 1 TO 30 
FOR i 1 TO 30000 
NEXT i 

NEXT | 


the times are : MS Basic (b) or (d) = 52 sec 


© The Essential MacTutor, Vol. 3 


ZBasic 3.04 z 7 sec. 


Please realize that now the rules have changed. These are 
times for a loop inside another loop. But the time difference is at 
least 5X. 

In the Random Disk I/O benchmark for ZBasic there is an 
extra RECORD statement in the PUT benchmark. With this line 
deleted the result was 16 sec. for PUT and 7 sec GET. That's a 
2 to 3 times advantage over the MS Compiler. 

In the Sequential PRINT# benchmark a comma delimiter is 
printed to the file in a corrected benchmark (with PRINT 
#1,x$;","). When corrected the Sequential INPUT# routine does 
notcrash. In fact the crash could have been avoided by setting the 
string length error checking flag on in the ZBasic configuration. 
The new times are PRINT#=27 sec and INPUTS! = 14 sec. Also 
if the string is 200 characters long instead of one character, the 
ZBasic times are 72 sec for PRINT# and 232 sec for INPUT#; 
MS Compiler times are 193 sec for printand 921 sec for INPUT#. 

In summary, it appears after all this that ZBasic is better than 
the original benchmark had indicated. Because of this and the 
support and determination that Zedcor has to make ZBasic 
successful, I have to say that the two products have an equal 
rating (MS Compiler hada slight advantage before). But the war 
is not over. Zedcor is working on more bug repairs and improve- 
ments. I hope that Microsoft will be doing the same. The 
competition is good, but I hope that we haven't gone too far off 
the deep end with faulty benchmark tests. 

Let's step around the controversy surrounding the continu- 
ing saga of Basic Wars to get into some programming. I'm still 
wondering when the dust will settle. Of course, the implemen- 
tation of our programming efforts here will be different depend- 
ing on the version of Basic that we use. I'm extremely grateful for 
the library routines that have been provided by CLR thus far. 
There are two new library packages from CLR: Graph3DLib and 
VWLib. CLR Graph3DLib allows you to access Apple's 3D 
graphics package from within your MS Basic program. CLR 
VWLib allows you to play VideoWorks movies from your MS 
Basic program. 


Graph3DLib 


When will I ever want to use 3D graphics anyway? Much 
of the time two dimensional graphics will be sufficient for what 
you would like to display (examples: a map, a x-y graph), 
however, there are some types of data or some objects that are 
difficult to expressin 2D. With other types of graphics where you 
want to show depth or perspective just as your eye would truly see 
it. (examples: a orthographic picture, a painting or illustration, x- 
y-z graph, animation). As they say: "A picture is worth a 
thousand words". Sometimes, the visualization of something can 
mean the difference between understanding and confusion. 


Intro to 3D 


First we should think about what is going on in the 3D world 
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vs. the 2D world. When you look at your computer screen (or 
when graphics are output to your screen or printer) you see a 
plane with points or lines on the plane which are arranged so as 
to display what we call 2 dimensional graphics. Your Macintosh 
screen is only capable of displaying two dimensional objects. 
When objects are seen in three dimensions, an object which is 
Close to us seems larger than the object appears when it is far 
away. The trick is converting the 3 dimensional display into 2 
dimensions so we can display it on the Macintosh screen. The 
new CLR library Graph3DLib will assist us in this conversion. 

Way back in algebra I was taught that a straight line is 
represented mathematically by the equation y = mx + b. Many 
of you remember this. The m and b are constants where m is the 
slope of the line and b is the value of y when x = 0. Plotting this 
equation (where only x and y are involved) requires only 2 
dimensions, one for x and one for y. 

In three dimensions, the equation of a line (y = mx+b) 
would appear only in the x-y plane. There would be no displace- 
ment in the z direction as z is a constant (z=0) in the equation. It 
should be noted that the axes shown are pointing in a positive 
direction. Thereare various mathematical equations involving x, 
y and z as variables in the same equation. This type of equation 
can best be visualized by building a 3D model of the equation. 


We haveall seen 3D models of one sort or another. Remem- 
ber the 3D models of molecules used in physics and chemistry to 
help the student visualize the subject being studied. If you take 
a3D modelin your handand lookatit you will see that the various 
coordinates of the model will look larger or small to the human 
eye depending on the angle which уоп аге viewing the model (i.e. 
parts in the back are further away and therefore appear to be 
smaller to the eye). Now for just a moment, pretend you are 
looking at one of these models through a glass window. If the 
model is smaller than the window, you can see the entire object. 


379 


If the model is bigger than the window, you can only see the part 
of the object that is in line with your eye and the window. 

Note that it also depends on where you are standing (at what 
angle to the right or left of the window) and where the model is 
located. The size of the object makes a difference too. If the 
model is close to the window and very large you may not be able 
to see the entire model (kind of like looking straight into the side 
of a wall in Maze Wars). 

I found that using CLR Graph3DLib was both easy and 
hard. Theconcepts are easy to execute but the hard part is finding 
just the right angle to view the object. Of course that won't be a 
problem is you are going to rotate the object anyway. First it is 
important to understand how the coordinate axes are organized. 


The coordinate axes are not explained in the CLR Graph3DL ib 
manual. In order to be consistent with the Macintosh screen 
coordinates the axes are arranged differently. The x axis points 
to the right, y axis points down (toward higher screen coordinate 
numbers) and because the y axis is pointing down the z axis must 
pointinto the Macintosh screen (z is perpendicular to x and y axes 
and must conform to the "right hand rule"). 


Making your own 3D! 


The graph3D statments use a variable type called fixed 
point (a static variable). Like single precision numbers, fixed 
point numbers are four bytes long. But, Basic does not have the 
fixed variable type. Therefore, Graph3DLib uses single preci- 
sion numbers to store the fixed point numbers. Graph3DLib 
provides conversion statements to convert to and from single 
precision and fixed point. The manual explains the conversion 
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statements sufficiently. The conversion of numbers is the most 
cumbersome of the entire 3D process. Beware! If you forget to 
convert a number, the routines won't work properly and you 
probably think that it is the routines fault. Beware of pilot error! 
You may want to initialize all the variables you will use at the 
beginning of the program and use them as needed in the 3D 
statements. For example you may want to set the variable zero! 
to '0' using Fs2Fix0!,zero! at the beginning of your program so that 
the variable zero! will already be converted when needed. All3D 
statements use the fixed point variables so remember to convert 
to fixed point first. 

To use Graph3DLib you first open up a 3-dimensional 
drawing port with the OpenPort3D statement (note there is a typo 
in the manual on page 7... Open3DPort should be OpenPort3D). 
You may specify more than one port if you want to use multiple 
windows for your output. 

The next step is to specify a viewport. A viewport is like the 
viewing window a mentioned above; a viewport identifies what 
coordinates will be able to be seen in the 3D drawing port. A 
viewport is identified in two-dimensional screen coordinates. 
You indicate the screen rectangle in which the drawing will be 
made. 

Next our 3 dimensional coordinate system will be mapped 
to the viewport rectangle by using the LookAt statment. LookAt 
tells the viewport what coordinates we will ‘look at' through the 
viewport. This can be a bit confusing unless you think of the 
viewport as an x-y plane and lookat is defining the 3D coordi- 
nates of the plane. The following statements from my function 
demo program will set the viewport coordinates from -10 to 10 
in the x direction (х1=-10, x2=10) and -10 to 10 in the y direction 
(у1=-10 and y2=10). 


Fs2Fix -101,x1! 
Fs2Fix -10!,y1! 
Fs2Fix 10!,x2! 

Fs2Fix 10!,y2! 
LookAt x1!,y1!,x2!,y2! 


It is recommended that the center of the viewport be the 
origin of the coordinate system although it is not a requirement. 
If you try to rotate an object when the origin is on the edge of the 
viewport you won't be able to see the object when it rotates off the 
edge of the viewport. If the viewport is not a perfect square then 
the object will be drawn somewhat distorted. If you want it that 
way then there is nothing wrong with doing it that way. Notice 
that there is no mention made of the z axis when defining the what 
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we will LookAt when we see the viewport. Since we are looking 
(physically) at a two dimensional screen, Graph3DLib refer- 
ences the x and y coordinates (3D) to the x and y on the Macintosh 
screen (2D). When the z axis is shown it will have the proper 
dimensions in relation to the x and y coordinates. In other words, 
if the z axis is rotated so that it points in the vertical (2D y 
direction) then it will have dimensions of the vertical direction. 
You don't need to worry about it because the 3D package takes 
care of that for you. 


The only thing left to define before you can draw is the 
viewangle. The viewangle is defined as the horizontal angle (in 
degrees) subtended by the viewing pyramid. The viewing 
pyramid is defined by the pyramid formed by drawing lines from 
thecornersof the viewport to theeye. To visualize the viewangle, 
image you are standing very close to your window. If you are 
standing very close to the edge of your window you must turn 
your head a wide angle to see the edges of the window. If your 
eye was right on the surface of the window then you would have 
to {шт by 90 degrees to see the edge. This also gives you a very 
wide viewport. If you are standing much further away from the 
window, the angle which you must turn your head in order to see 
theedges is much smaller. According to the Graph3dLib manual, 
25 degrees is the normal perspective of the human eye. 10 
degrees gives the effect of a telephoto lens whereas a large 
viewangle of 80 degrees give the effect of a wide angle lens. 


You may specify the Pitch(x Angle), Yaw (y Angle) or Roll 
(z Angle) using the Pitch, Yaw and Roll statements respectively. 
By changing this angle before drawing the object will make the 
object appear to rotate in space. The Scale statement lets you 
shrink orexpand the drawing on each axis in the proportion factor 
specified. You may move the pen to any 2D or 3D coordinate 
(using MoveTo2D or MoveTo3D) and then draw lines from the 
pen location to another point (LineTo2D or LineTo3D). You 
may also draw from the current pen location to a point dx, dy or 
dz units away. (dx is a displacement in the x direction). There 
are a few math operation statements provided for doing math 
operations on fixed point variables, but they won't be faster than 
the operations in Basic because of the time Basic takes to call the 
library routines. 


The 3D function demo program sets up two viewports in the 
same window and calculates and displays the following 3D plots: 


Other functions may be substituted for the samples that I've 
used here. Some simple functions will provide some interesting 
patterns etc. While Graph3DLib is not fancy in that it doesn't 
have routines to draw circles and other shapes, you may find that 
it will still be a worthwhile product to include in your library of 
routines. It would have been nice if it inclued some of the 
functions found in other comercial 3D graphics packages. For 
example, the 3-Dimensional Graphics package for True Basic is 
much more complete with statements for circles, grids and 
oblique projections (but you have to use True Basic). 

For comparison purposes, I have provided a 2-dimensional 
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demo using MS Basic routines and another using CLR 
Graph3DLib routines (2D routines). The Graph3DLib routines 
run slower probably because of the time that Basic takes to access 
the library routines. If you are not going to use 3D graphics then 
you don't need Graph3DL ib. It is easier to draw the 2D stuff with 
the MS Basic routines rather than using the Graph3DL ib stuff. 

You may want to experiment with the view angles for 
special effects. It could be interesting. The demo programs are 
available on the source code disk disk through the MacTutor 
store to save you trouble when typing them in. Feel free to modify 
or play with them as you like. 


Using VWLIb 
Another new library package from CLR is the VWLib 


(Videoworks library). VideoWorks is a powerful program for 
creating animation sequences called "movies". CLR VWLib 
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allows you to play these VideoWorks movies from MS Basic. 
VideoWorks is NOT included with CLR VWLib. 

First, a few words about VideoWorks. Many of you have 
been impressed with the animation produced by VideoWorks. 
You may create animation by two methods: real time recording 
and frame by frame. With real time recording you can records 
animation as you move objects around on the screen. In frame by 
frame animation, you produce each frame one at a time. Objects 
may be imported from MacPaint or MacDraw (or equivalent 
applications) or you can use CheapPaint, a frame editor built into 
VideoWorks for creating or editing. Creating animation is very 
easy (at least it was for me). You may add sound effects to the 
animation (sound effects are included). I can see why MacUser 
magazine gives VideoWorks a five mice rating! 

There were only a couple of annoying drawbacks with 
VideoWorks which I'd like to mention. One of the worst was 
copy protection. UGH! This is worst now that the CLR VWLib 
supports playback of movies. And since VWLib requires that 
VideoWorks be present it is a pain and a half! It is better with a 
hard disk however, because after I installed VidoWorks on my 
hard disk I could run it without the system disk being present. The 
other problem that I noticed was that the DEMO movies would 
notrun in demo mode when not in the same folder as VidoWorks. 
This implies that VideoWorks has not been updated or improved 
since HFS was introduced. I won't go into any other comments 
about VideoWorks as it is a product that has been out for quite 
awhile and many of you are already familiar with it. 


Professor Mac goes to the movies 


Using CLR VWLIib is just about as easy as playing back а 
movie from within VideoWorks. There are a couple of things 
that you must do first. First, the VWLib must be on the same 
directory (same folder) as Basic even for MS Basic 3.0. Also if 
you want to use sound you must have the sound file in the same 
folder as Basic. The routine vwopen from the VWLib will bomb 
if everythng is not in the same HFS folder as Basic. Apparently 
this routine is not at all HFS compatible. Movies can be in any 
folder if you are using Basic 3.0. If you have not upgraded to 3.0 
I would strongly recommend it. 

There are two ways to play a movie. The first way plays 
back the entire move. The second way advances the movie one 
frame at a time so that you may have other things going on at the 
same time. In the demo program, I used the second method and 
added optional SpeechLib support (for those of you that have 
CLR SpeechLib). The demo is provided so you can see for 
yourself how it works. 

My thanks go to Hayden software for supplying me with a 
sample copy of VideoWorks. I can highly recommend it to 
anyone that wants to do any kind of animation. (Hayden Soft- 
ware, 600 Suffolk St.,Lowell, MA 01854) Ask them to remove 
their copy protection. VideoWorks is a trademark of Mac- 
roMind. 

The CLR Graph3DLib ($35) and VWLib ($50) are avail- 
able from Clear Lake Research, 5615 Morningside, Suite 127, 
Houston, TX. 77005 (1-800-835-2246 X199 except Kansas). 
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Editor's Remarks 


[This program points up some serious problems with the 
new Basic Compiler, version 1.0, if you try to compile this demo. 
Nearly all Basic programs must include at least one library 
statement if they are to use any of the CLR toolbox routines that 
are now distributed by Microsoft. This demo has two such 
statements; опе for the video works stuff (VWLib) and one for 
the speech stuff (SpeechLib). Naturally the goal of compiling a 
program is to create a stand-alone application. So you want to 
combine the library files with the basic program. Library files are 
machine code resources that are called from Basic as subroutines. 
They can be merged with the resources of the main program by 
using the statement mover program. According to the documen- 
tation, you use the name of the program in the library statement 
when the library resources are part of the program file. When this 
was tried with the video works demo, the video works library 
routines bombed with a run time error 5. It appears the VWLib 
makes incorrect use of the file refnum so that the library will not 
work properly under HFS unless the VWLib is available as a 
seperate file at the same level as Basic. Thus there is no way to 
create stand alone applications which use the VWL ib. The library 
statement is also a very poorly designed statement since it 
requires a complete path name to find the library, which is a 
definite no-no on the Macintosh. If you create a program and 
move the libraries into the program file, the program will only 
Work if the user doesn't change the program name or move it to 
another folder and change the path name! Nothing could be more 
ridiculous than to include in your program documentation the 
warning "Please do not move this program to any folder or 
change its name or it will fail to run!". This single statement 
shows that Microsoft has yet to fully address the HFS issue, even 
in version 3.0. The correct solution of course is for the Microsoft 
run time package to detect a file not found error at run time when 
the library statement executes and put up a Standard File Dialog 
asking the user to locate the needed library file. The library 
statement also needs an option to indicate the required library is 
part of the compiled program file so that no path name is needed. 
It is assumed that the Basic run time package knows how to find 
itself, but then seeing the problems Microsoft Fortran has had 
with HFS, maybe that is a bad assumption. Obviously no serious 
commercial Basic applications can be created that must use 
libraries until this bug is fixed. -Ed] 


' 3D Function Plot 
' eMacTutor 1987 
' By Deve Kelly 


DIM y!C100, 100) 

' Be sure to set librery volume to your own volume 
LIBRARY "Нага Disk:Basic:CLR Graph3D:Graph3DL ib" 
LIBRARY "Hard Disk:Basic:CLR Graph3D: Toolbox" 
initialize: 

WINDOW 1 'Be sure а window is open! 

OpenPort3D ‘Set 3D output to window 1 

' Next initialize variables to be used in library calls. 
х11=0:х21=0:11=0:2!=0: гего!=0 
хрі!=0:0рі!=0:2рі!=0:2!=0 

xAngle!=8 : yAngle!=8:zAngle!=8: Angle! = 
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SetRect viewrect1$C1),50,50,250,250 ‘set the viewport rect. 


convert single precision to fixed point values 
Fs2Fix -10!,x1! 

Fs2F ix -18!,y1! 

Fs2Fix 10! ,х2! 

Fs2Fix 10! ,y2! 

Fs2Fix 8! zero! 

Fs2F ix 45! ,xAngle! 

Fs2F ix 45!,yAngle! 

Fs2F ix 0! ,zAngle! 

Fs2F ix 25! , Angle! 

viewport viewrect 1%¢ 1) 

FRAMERECT CVARPTR(viewrect 1%( 1222 
SetRect viewrect2%¢ 1),275,50,475,250 
LookAt x1!,y1!,x2!,y2! 

ViewAngle Angle! 

roll zAngle! 

yaw yAngle! 

Pitch xAngle! 

GOSUB Drawaxis 

GOSUB Drawing! 

viewport уіенгесі2%С 1) 

FRAMERECT CVARPTR(viewrect2%¢ 122) 
GOSUB Drewaxis 

GOSUB Drawing2 

Жы MOUSE(2) O 1:WEND 


Drewexis: 
' Draw x axis 
moveto3d 2его! , его! ,zero! 
lineto3d x2!,zero!,zero! 
' Drew y axis 
moveto3d zero! , его! , zero! 
lineto3d zero! ,x2! ,zero! 
' Drew z exis 
moveto3d zero! , 2его! , его! 
lineto3d zero! , его! , х2! 
RETURN 
Drewingl: 
Calculate: ' calulete equation y = SINCz) 
FOR x!-0 TO 10 
FOR 2-0 TO 10 
y! Cx, z)-SINCz) 


Plot: 
FOR х!-0 TO 10 
Fs2F ix x!,xpt! 
noveto3d xpt! zero! ,zero! 
FOR 2!=0 TO 10 
Fs2Fix y(x,z),ypt! 
Fs2Fix z!,zpt! 
lineto3d xpt!,ypt!,zpt! 
NEXT 
NEXT 
RETURN 
Drawing2: 
Calculate: calulate equation y = 9 - (772) 
FOR x!=-5 TO 5 
FOR z=-5 TO 5 
y!(xt5,215)29-Cz^2) 
NEXT z 
NEXT x 


ot: 
FOR x!=-5 Т0 5 

Fs2Fix x!,xpt! 

Fs2Fix y!(x+5,8),ypt! 

Fs2Fix -5!,zpt! 

moveto3d xpt!,ypt!,zpt! 

FOR z!=-5 TO 5 
Fs2Fix y(x+5,z+5),ypt! 
Fs2Fix z!,zpt! 
lineto3d xpt!,ypt!,zpt! 
XT 


P1 
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NEXT 
RETURN 


' 2D Circle Demo 
' @MacTutor March 1987 
' By Deve Kelly 
' MS Basic version 
WINDOW 1,°", (122, 22)-(424,324),3 
MainRoutine: 
DIM x!(360),y! (360) 
pi!=3. 141593 
DEF FNrad(deg)=pi ! *deg/ 180 
LOCATE 2,2: TEXTSIZE 9:INPUT "Enter step value: «25» 


ip 
IF 51р=0 THEN Stp=25 
CLS 


PENMODE(8) 
LOCATE 2,2: PRINT"Step =";Stp 
FOR n=1 TO 360 
AnglesFNrad(n) 
x(n =CSINCAngle)+1)/2*WINDOW(2) 
y(n=(COSCAngle)+1)/2*WINDOW(3) 
NEXT n 
FOR п=1 TO 360 STEP Stp 
m=n+ 1 
WHILE non 
MOVETO x(n), уп) 
LINETO x(m), ym) 
m=m+Stp 
IF 1360 THEN n=! 
END 


we, 
д 


NEXT n 
LOCATE 25,2:PRINT "Press any key"; 
key$= nu 
WHILE key$= "н 

key$- INKEY$ 


WEND 
WINDOW CLOSE ! 
END 


' 2D Circle Demo 

' @MacTutor March 1987 

' By Dave Kelly 

' CLR Greph3DLib version 
" Requires CLR Greph3DL ib 


' Set your own volume names 

LIBRARY "Herd Disk:Basic:CLR Graph3D:Graph3DL ib" 
LIBRARY "Hard Disk:Besic:CLR Graph3D: ToolBox" 
initialize: 

WINDOW 1,°", €122,22)-(€424,324),3 

OpenPort3D ‘Set 3D output to window 1 

' Next initialize variables to be used in library calls. 
х1!=0:х2!=0:01!=0:021=0 

s!-0:t!-0:u!s0:v!-0 
xAngle!=8:yAngle!=0:zAngle!=0: Angle! =0 

SetRect уіенгесі1%(12,2,2,300,300 ‘set the viewport rectangle 
' convert single precision to fixed point values 
Fs2Fix 0!,x1! 

Fs2Fix 8! ,y1! 

Fs2Fix 1!,x2! 

Fs2Fix 1!,y2! 

Fs2Fix 8! ,xAngle! 

Fs2Fix 8! ,yAngle! 

Fs2Fix 8! ,zAngle! 

Fs2Fix 25! , Angle! 

viewport viewrect12( 1) 

' freme rect. so we can see it. 

FRAMERECT CVARPTR(viewrect 18€ 122) 

LookAt x1!,y1!,x2! 02! 

ViewAngle Angle! 

roll zAngle! 
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yaw yAngle! 
Pitch xAngle! 


MainRoutine: 
DIM x! (369), y! (360) 
pi!=3. 141593 
DEF FNrad(deg)=pi ! *deg/ 180 
LOCATE 2,2:TEXTSIZE 9:INPUT "Enter step value: «25» 


p 
IF Stp= THEN Stp=25 
CLS 


PENMODE(8) 
LOCATE 2,2: PRINT'Step =";Stp 
FOR n-1 TO 369 
Angle=FNrad(n) 
x! Cnd=CSINCAngle)+1)/2 
у! Cnd=(COSCAngle)+1)/2 
NEXT n 
FOR n=1 TO 360 STEP Stp 
т=п+ 1 
WHILE mon 
Fs2Fix x!(n),s 
Fs2Fix у! Сп), + 
Fs2Fix х! См), и 
Fs2Fix у! Ст), у 
MoveTo2D $, { 
lineTo2d u,v 
m=m+Stp 
IF т 360 THEN m=! 
D. 


"St 


NEXT n 
LOCATE 25,2:PRINT "Press any key"; 
key$="" 
WHILE key$="" 

key$=INKEY$ 


WEND 
WINDOW CLOSE 1 
END 


' Professor Mac's Movie Demo 

' eMacTutor 1987 

' By Dave Kelly 

' Requires CLR VWLib (VideoWorks not required) 
' with optional support for CLR SpeechLib 


CLEAR, 30000! 
false=0:true=NOT false 
LIBRARY "Hard Disk:Basic:CLR VWLib:VWlib" 
ON ERROR GOTO 10 
SpeechS tatus=true 
LIBRARY "Hard Disk:Basic:CLR SpeechLib :Speecht ib" 
ON ERROR GOTO 2 
IF SpeechStatus=true THEN 
SpeechHend! =0! 
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SpeechErr$-0 

Phon$="" 

SpeechOn "",SpeechHend! ,SpeechErr% 

ReaderString SpeechHend!, "He110",Phon$,SpeechErrt 
END IF 


DIM A$C300) 

refnum%=0 

done£2-0 

mov ie$="Hard Disk:Mactutor*:Mar87:Professor Mac Movie" 


018 
ON ERROR GOTO 20 
vwopen novie$,0,0,refnunt 
ON ERROR GOTO 0 
ON TIMER (4) GOSUB Waiti 
TIMER ON 
advance: 
vwenimate refnumZ ‚бопе 
IF done%=8 THEN advance 
done: 
IF SpeechStatus=true THEN SpeechOff SpeechHend! 
vwclose refnum$ 
INITCURSOR 


TIMER OFF 

IF SpeechStatus=true THEN GOSUB Speak 
ON TIMER(C 13) GOSUB Wait2 

TIMER ON 

RETURN 

Wait2: 

IF SpeechStatus=true THEN GOSUB Speak 
TIMER OFF 

RETURN 


Speak : 


GET (15, 152- (85,552, A3 

SoundOutString SpeechHand! ,Phon$, бреесһЕгг% 
PUT (15, 152, AS, PSET 

HIDECURSOR 

ReaderString SpeechHand! ,"Welcome to 
MacTutor" ,Phon$, SpeechErrs 

RETURN 


10 NoSpeech: 

IF ERR=53 THEN SpeechStatus=false 
RESUME NEXT 

20 NoMovie: 
novie$-F ILES$( 1, “VWSCVWZP" ) 

IF movie$="" THEN END 

RESUME 
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Basic School Аш 


Scrolling in ZBasic 


ZBASIC SCROLLING 


Thus farithas not been made widely known what or how the 
ZBasic Scroll Buttons could be used. Of course, they return a 
value relating to the position of the scroll bar, but until now how 
to use the scroll bar for scrolling text has eluded me. Part of the 
problem comes when reading in the ZBasic manual which states 
"SCROLLing windows with Buttons or Scroll bars will cause 
interesting AND unpredictable results." (pg. D-56). Thisimplies 
to me that SCROLLing is not meant to be used with Scroll bars. 
However, after questioning Zedcor about this, they sent me a 
demo scroll program which does just that, scrolling with Scroll 
bars. There is a requirement however. The routine doesn't quite 
Work right without version 3.05 or greater. Earlier versions of 
ZBasic don't clear the screen and update properly. [In particular, 
the current official version 3.03, when doing a slow scroll, begins 
mashing the bottom window frame to anice black mush. The next 
official release is due April 2nd. A new manual is also being 
prepared. -Ed] Hopefully, by the time you are reading this you 
have already upgraded to version 3.05 or greater. Zedcor really 
has been very good at updating those people who have already 
purchased ZBasic. You should know that they want $19.95 to 
upgrade if you have had your copy for 60 days or more. Most of 
the upgrades have included significant improvements which 
should have worked to begin with (those upgrades should be 
free!). Most improvements have been bug fixes. I'm looking 
forward to the much needed editor that will soon be included in 
a future upgrade. Zedcor promises to soon release an editor that 
will highlight keywords in bold face similar to the MS BASIC 
editor. 

Well, back to SCROLLing. The Zedcor demo program 
demonstrates to us how we can use Scroll bars and the SCROLL 
statement to scroll text. The SCROLL statement allows you to 
scroll a selected area of a window. Although the concept of how 
the scrolling works is simple, the implementation is somehow 
complex. The thing that makes it seem complex is the many 
variables that are required to keep track of how much the window 
needs to be scrolled and which line of text should be displayed at 
the top of the screen. If you take time to study out the routine you 
can easily adapt it for use in your own programs. 

The Scroll bars in ZBasic are set up by using the SCROLL 
BUTTON statement. A SCROLL BUTTON is a control which 
works much like other buttons in that when ON DIALOG is used 
to trap events the BUTTON (button number) function will retum 
the value of the SCROLL bar's position. The syntax for the 
SCROLL BUTTON is: 


SCROLL BUTTON [#] button number, current value [[, min 
value], max value][,[page up/down][, (x1,y1)- (x2,y2)] [, type]]]. 
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The unfortunate thing about the ZBasic Scroll bars is that 
there is no provision for scrolling the text being edited in an EDIT 
FIELD statement. (Up to now, none of the versions of BASIC 
have provided a way to do this, except the still undocumented 
statements for text edit in version 3.0 of MS BASIC). The 
alternative is to use the toolbox statements (which are not yet 
proven to be reliable) to access the text edit routines in the ROMs. 
This would still require some manipulation to use the Scroll bars 
with the ROM text edit routines. It would be nice to have routines 
which automatically link text edit capabilities with the scrolling. 
Even some routines that linked scroll bars and text edit half way 
would be a help. For reference, take a look at the January 1986 
issue of MacTutor. In that article Ishow examples of using CLR 
Libraries for scrolling text. (These libraries are now included 
with version 3.0 of MS BASIC and also with the MS BASIC 
Compiler). The CLR Libraries statements make using Scroll 
bars easier, but even these are limited. ZBasic's scroll bars may 
be considered as totally independent of other functions or state- 
ments. CLR Libraries are easier to implement (but they don't 
work with ZBasic). 

There are two kinds of scrolling demonstrated by Zedcor's 
demo program. SoftScrolling is done by scrolling the text by one 
pixelatatime. Normal scrolling will scroll one line ata time. The 
line height is calculated by getting font information via the 
GETFONTINFO toolbox call. For most text applications the 
normal scrolling is more appropriate. Softscrolling is somewhat 
slow because it takes more steps to scroll one pixel at a time than 
to scroll a whole line. 


Z-INDEX Scrolling 


ZBasic has provided BASIC programmers with some 
unique statements not found in other versions of BASIC. We will 
discuss one of these now in order to familiarize ourselves with it. 
The INDEXS statement provides users with an automatic way to 
insert, delete, edit and find data stored in an array. 

The Macintosh version of ZBasic allows ten INDEX$ 
arrays to be active (only one INDEXS array in other versions). 
The array looks and feels much like any other array that you may 
decide to use except that there are special statements to enhance 
array manipulation. The first thing that is done when using 
INDEXS statements is to set up some memory which can be used 
for the arrays. This is accomplished with the CLEAR nnnnnnn 
[,index#] statement, where index# is the number of the INDEX$ 
array to be used. You may consider this as a multi-dimension 
array except that the second dimension range is from 0 to 9. You 
may use the MEM [(index#)] to determine the total memory 
available. ZBasic allows you to insert, replace, delete and find 
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data with the following statements: 

INDEX$ (element! [,index#]) = string : use to set an array 
element to a string. 

INDEXSI (element# [,index#]) = string : use to insert a 
string at element#. The array contents in elements equal to or 
greater than element# are moved to the next higher element# to 
make room for the new element. 

INDEX$D (element# [,index#]) = string : use to delete a 
string at element#. The array contents in elements equal to or 
greater than element# are moved down to the next lower 
element#. 

Clearly these are valuable statements especially when in- 
serting data into a file or into a proper order. The example 
program demonstrates the use of INDEXS to insert data into a 
list. The scroll demo has been integrated into the program to 
scroll through the list. Also the INDEXF statement is used to 
search for a set string and the program lists the remainder of the 
list starting with the value searched for. To reset to all records, 
just find the first record again. There could be much more 
refinement to the program... I'll leave that up to you. The 
programs are sufficient examples to get you started. One prob- 
lem I ran into while working with the INDEX-SCROLL example 
is that I forgot to access the first window after closing the second 
window (which was used for input). By simply using the 
WINDOW #1 statement the output will then go to the first 
window for subsequent statements. If you don't do this you may 
get a bomb because you closed the window you specified for 
printing, but didn't respecify a new window. There are a few 
other subtle things that may affect the way your program works. 
The Zedcor example uses GOTO occasionally. I try to stay away 
from this one whenever I can, but since the Zedcor routine works, 
why re-invent the wheel. You may want to change all GOTOs to 
GOSUBs to be consistent with the structured programming 
approach. I modified some of the GOTOs already so there are 
fewer than there used to be. 


REM ххх%ж%ххх%% Text Window Scroll Bar(s) Example 
REM ZBasic 3.05 or Greater 1/87 А.б ZEDCOR, INC. 
REM with modifications & explainations 2/87 
REM by D. Kelly MacTutor™ 

REM ХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХХ eoe x 
WINDOW OFF 

COORDINATE WINDOW 

WIDTH -2 

False = Ø : True = NOT False 

X=MEM(-1) :REM *** Disable Line Wrap *** 

WINDOW 1, "Untitled", (58,50)-(450,255),9 

REM ** Initial Window Size ** 

TEXT 4,9 

MENU 1,0, 1, "File" 

MENU 1, 1, 1, "Open" 

MENU 1,2,9,"-" 

MENU 1,3,1, "Quit" 

MENU 2,90, 1, "5сго11 Туре" 

MENU 2, 1, 1, "Normal Scroll" 

MENU 2,2, 1, "Soft Scroll" 

DIM Ascent,Descent, WidMax,Leading 

CALL GETFONTINFOCAscent) 
Height=Ascent+Descent+Leading REM * Font Size * 
GOSUB "Openfile" 

OV-False 

OH=True 


386 


Softscroll=False : REM ** Softscrol] 
SCROLL BUTTON 1,0V,0V,TL-1,7L/10,,1 
SCROLL BUTTON 2,0H,0H, 255, 10, ,2 

ON DIALOG GOSUB "Dialog" 

ON MENU GOSUB "MenuEvent" 

WINDOW? 1,A$ : REM *** File name to Title *** 

DIALOG ON 

MENU ON 

BREAK ON : REM **g-Normal Scroll 1=Soft Scroll ** 
"Loop" : GOTO "Loop" : REM Main Event Trapping Loop 


DIALOG OFF: BREAK OFF :MENU OFF 

REM *** Turn OFF dialogs for rest of PGM **x 
"MenuEvent" 

Menunumber = MENUC?) 

Menuitem = MENUC1) 

LONG IF Menunumber = 1 

IF Menuitem = 1 THEN GOSUB "Openf ile" 

IF Menuitem = 3 THEN STOP 

END IF 

ur ies = 1 THEN Softscroll = Ø ELSE Softscroll = 1 


z Soft-Scroll Flag ** 


RETURN 

"Dialog" : D-DIALOGCOD : REM Dialog Events here.. 

ON D GOTO 

"Button", "x", "ACTIVE", "боАмаџу", "Update", "X", "X", "Zoom", "Zoom" 
"ACTIVE" 


WINDOW *"DIALOGCD) 
RETURN : REM ** Activate this Window ** 
"Button 
IF DIM OGCD2e1 THEN Buttonvalue-BUTTONC12) ELSE "Side" 


X=0V-But tonvalue 
IF ABSOO > SL THEN OV-Buttonvalue : CLS : GOTO “Update” 
IF Х›0 THEN DV=Height :DL=-1 : Leading=@ : P=Ascent ELSE 
DV=-Height :DL=+1 :Leading=SL+1 : P=CSL-1)*Height+tAscent 
WHILE OV<>Buttonvalue 

IF Softscroll THEN DV=SGNCDV) : 11=1 ELSE II-Height 

FOR II-II TO Height 

SCROLL (9,0)-(W6,W7),,DV : REM SCROLL 1 line or 1 Pixel 
PRINT 3(-BUTTONC2)*WidMax, P*CDV*CII-Height22); INDEXKCOV- 
itLeading); 


T 
OV=OV+DL : REM Remove NEXT if soft-scroll not used 
WEND  : RETURN 


"Zoom" 
рК , RETURN : REM ERASE IF ZOOM-IN OR ZOOM OUT 
SCROLLCI, Ø)-CW6, W7), COH-BUTTONC2))*W idMax, 8: OH=BUTTONC2) 


"Update" 

WO=WINDOWC6)-1 : W7=WINDOWC7)-1 : SL=W7/Height 
FOR II= OV TO OV+SL-1 : REM Re-Draw Full Screen 
PRINT 3(-BUTTONC2)*WidMax, (11- 


OV)*He ight+Ascent ); INDEX$C(I1); 


NEXT 
COLOR 0 :BOX FILL 08,SL*Height TO W6,W7 :COLOR -1 
ыды *Erase Bottom* 


RETURN : REM **** Just RETURN routine **** 


"GoAway" 

STOP 

"Openfile" : A$-FILESSCI, "TEXT", , VS) 
IF A$="" THEN BEEP : STOP ELSE CLS 


OPEN "I", #1, A$, 1, V3 

CLEAR LOFC15*32 

TL=8 

IF MEM-0 THEN STOP 

WHILE NOT EOFC1) 

REM ****) Read TEXT file into INDEX$ array <***** 
LINEINPUT! 1, W$ 

INDEX$CTL2-w$ 

TL=TL+1 : REM FILL INDEX$ FROM FILE 
WEND 

CLOSE 
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RETURN 

REM ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
REM ** Some Possible Changes: 

REM ** Line 210 Change 'ABSOO > SL' to 'ABSOO > 1' Single 
REM Line Soft 

REM ** Add ‘CLEAR Ø' to Erase INOEX$ Array When Text 

REM Window Closed. 


REM Е52225522155425522222525222255222224422252222422522252522245. 


REM *****xx** INDEX Scroll Bar(s) Demo 

REM *** 7Basic 3.05 or Greater 

REM *** by D. Kelly MacTutor™ April 1987 

RE M * XoXxXxoroooroooootororororooororooreroeoooeoooeooeoee 
WINDOW OFF 

COORDINATE WINDOW 

DIM STC30, 1) 

CLEAR 11000 

TL =й 

WIDTH -2 

False = Ø : True = NOT False 

X-MEMC- 1) :REM *** Disable Line Wrap 

WINDOW 1,"INOEX / SCROLL Demo",(50,502-(450,2552,9 
REM ** Initial Window Size ** 

TEXT 4,9 

MENU 1,0,1, "File" 

MENU 1,1,1, "Quit" 

MENU 2,0, 1, "Scroll Type" 

MENU 2, 1, 1, "Norma! Scroll" 

MENU 2,2, 1, "Soft Scroll" 

MENU 3,0, 1, "INDEX Demo" 

MENU 3, 1, 1, "Add Record/A" 

"Insert Record/I" 

, Edit Record/E" 

MENU 3,4, 1, "Find Record/F" 

MENU 3,5,1, "Delete Record/D" 

DIM Ascent,Descent, WidMax,Leading 

CALL GETFONTINFOCAscent) 
HeightzAscent*Descent*Leading :REM * Font Size х 
0У-Ғә1зе 

OH=True 

Sof tscroll=False : REM Softscroll = Soft-Scroll Flag 
SCROLL BUTTON 1,0V,0V, TL-1,TL/10,,1 

SCROLL BUTTON 2,0H,0H, 255, 18, ,2 

ON DIALOG GOSUB "Dialog" 

ON MENU GOSUB "MenuEvent" 

DIALOG ON 

MENU ON 

BREAK ON : REM 0=М№огта1 Scroll 1=Soft Scroll 
“Loop” : GOTO "Loop" : REM Main Event Loop 


DIALOG OFF: BREAK OFF :MENU OFF 

REM Turn OFF dialogs for rest of PGM 
"MenuEvent" 

Menunumber = MENUCO) 

Menuitem = MENUC1) 

ON Menunumber GOSUB "File","Scroll","Index" 
MENU 

RETURN 


"File" 

IF Menunumber = 1 THEN STOP 

RETURN 

"Scroll" 

IF Menuitem = 1 THEN Softscroll = Ø ELSE Softscroll = 1 
RETURN 

"Index" 

ON Menuitem GOSUB "Ада", "Insert", "Change", "Find", "Delete" 
RETURN 


= 
m 
Ж. 
c 
сз 
- & 
оз М 
`% 
РСЕ 
~ 


"Dialog" : D=DIALOG(@) : REM Dialog come here.. 

ON D GOTO "Button", "X", "Active", "GoÀway", "Update", "x", 
"xX", "Zoom", "Zoom" 

"Active" 


WINDOW *"DIALOGCD) 
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RETURN : REM ** Activate this Window ** 

"Button" 

IF DIALOG(D)=1 THEN Buttonvalue=BUTTON( 1) ELSE "Side" 

X=0V-But tonvalue 

IF ABSOO > SL THEN OV=Buttonvalue : CLS : GOTO “Update” 

IF Х›0 THEN DV=Height :DL=-1 :Leading-8 :P=Ascent ELSE 
DV=-Height :DL=+1 :Leading=SL+1 :  P=CSL- 

1)*He ight+Ascent 

WHILE OV<>Buttonvalue 

IF Softscrol] THEN DV=SGNC(DV) : 11=1 ELSE II-Height 

FOR II=II TO Height 

SCROLL (8,0)-CW6,W7),,DV : REM SCROLL 1 line or 1 Pixel 

PRINT %C-BUTTONC2)*WidMax, P*C(DV*CII-Height222; INDEXéCOV- 

itLeading); 

NEXT 

OV=OV+DL : REM Remove NEXT if soft-scroll not used 

WEND  : RETURN 

"Zoom" 

CLS : RETURN : REM ERASE IF 700М-ІМ OR ZOOM OUT 

"Si " 

SCROLL(2,92-CWN6,W7), COH-BUTTONC2) >*W idMax , 8: OH=BUTTONC2) 

"Update" 

WO=WINDOW(6)-1 : W7=WINDOWC7)-1 : SL=W7/Height 

FOR II= OV TO OV+SL-1 : REM Re-Draw Full Screen 

PRINT S(-BUTTON(2)*WidMax, CII- 

OV)*He ight+Ascent ); INDEX$C ІІ); 

NEXT 

COLOR 0 :BOX FILL 9,SL*Height TO W6,W7 :COLOR -1 

REM *Erase Bottom* 


RETURN : REM **** Just RETURN routine **** 
"GoAway" 

WINDOW CLOSE DIALOGCAD:RETURN 

"Insert" 

WINDOW 2, “Insert”, (180, 100)- C400 , 200), -263 
TEXT 2,0 : LOCATE 1,2 

INPUT "Insert record before 8:":М 

IF М<0 THEN М-0 

IF N>TL THEN N-TL 

INPUT "Insert record: ";W$ 

INDEX$I (ND = w$ 

TL = TL + 1 

WINDOW CLOSE 2 

WINDOW 1 

SCROLL BUTTON 1,0V,0V,TL-1,7L/10,, 1 
CLS:GOSUB "Update" 

RETURN 

"Add" 

WINDOW 2, “Insert”, (188, 100 )-С400, 200), -263 
TEXT 2,8 : LOCATE 1,2 

INPUT "Add record: ";W$ 

INDEX$ CTL) = w$ 

TL = TL + 1 

WINDOW CLOSE 2 

WIN 


DOW ! 
SCROLL BUTTON 1,0V,0V,TL-1,TL/10,,1 
RETURN 


"Delete" 

WINDOW 2, “Delete”, (100, 198)-(400, 200), -263 

TEXT 2,8 : LOCATE 1,2 

INPUT "Record number to delete: (<Ø to abort)";N 
IF №=0 THEN INDEXÉDOD : TL = TL - 1 

WINDOW CLOSE 2 

SCROLL BUTTON 1,0V,0V,TL-1,TL/18,,1 

WINDOW 1 

CLS :GOSUB "Update" 

RETURN 


"Change" 

WINDOW 2, "Change", C100, 100)- (400, 200), -263 

TEXT 2,0 : LOCATE 1,2 

INPUT "Record number to Change: (<Ø to abort)";N 
PRINT "Current record is ";INDEX$CND 

INPUT "Change record to:";w$ 

IF W$ = "" THEN W$ = INDEX$CND 


387 


INDEX$(N) = w$ 

WINDOW CLOSE 2 

WINDOW 1 

CLS:60SUB "Update" 

RETURN 

"Find" 

WINDOW 2, "Find",C100, 100-400, 200), -263 
ТЕХТ 2,0 : LOCATE 1,2 

INPUT "Record string to Find: ";и$ 
OV=INDEXF (W$) 

WINDOW CLOSE 2 

WINDOM 1 

SCROLL BUTTON 1,0V,0V, TL-1, TL/ 10, , 1 
CLS:GOSUB "Update" 

RETURN 


There is some new news on the BASIC WARS scene. 
Pterodactyl Software is back to work on the PCMacBasic com- 
piler. Version 1.96 is out and a new manual. Most of the 
improvements are in reliability. Functionally it appears to be the 
same BASIC as before, but with less problems with HFS. It now 
finds all of the necessary files no matter where they are located. 
PCMacBasic still has good potential as it is the only BASIC that 
will interface with MDS and MPW. MPW support is coming 
very soon. Mostof my comments from my previous reviews still 
hold except for what I have mentioned here. 


Stay in touch for more info on products for BASIC. Cur- 
rently ZBasic is at version 3.05, True Basic is at 1.1 (still), 
Softworks Basic (nochange), MS Basic interpreter 3.0, MS Basic 
Compiler 1.0, PCMacBasic 1.96. 

Any questions, just drop me a note care of MacTutor. I'm 
trying to answer some of your questions now. Please be patient 
because some of the questions you have asked involve changes 
that Zedcor is making as they constantly improve ZBasic. 
DIALOG statements which I commented on in the January 1987 
MacTutor do not work properly in versions before 3.05. If you 
compile the programs in this month's issue with anything earlier 
than 3.05 you will see that there are problems with those earlier 
versions. It has been extremely difficult to work with a product 
which has evolved so rapidly. When troubleshooting programs 
Ihave written, ithas been achallenge to determine if the problems 
were caused by bugs in the compiler or bugs in my source code. 
Check your own code first, then if you're pretty sure your code is 
оК you can start blaming the compiler. I've found times when 
both the compiler and the source code (my source code) was at 
fault. Please write if you are experiencing some difficulties. 
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Basic School 
Windows with ResEdit 


Windows are a fundamental of the Macintosh user inter- 
face. Back in March of 1985, Vol. 1 No. 4 of MacTutor (for those 
of you who were around back then) or starting on page 307 in The 
Best of MacTutor, Vol 1, I cover the basics of creating windows 
with MS Basic. Irefer you back to this reference for details. (You 
can get Best of MacTutor, Vol 1, through MacTutor for $24.95). 
Sorry to say, the new version of MS Basic and the MS Basic 
Compiler has only a small improvement to windows. MS Basic 
now allows six windows open at once instead of four. ZBasic has 
added window capabilities such as additional window types 
available including the ability to specify Zoom windows, go- 
away box, grow box, and rounded cornered windows. We can 
only hope that the next version of MS Basic will be more 
comprehensive. Notwithstanding this there are a few things that 
can be mentioned relating to windows. 

If you recall, a few months back, during our Basic Wars 
review, PCMacBasic was the only Basic to allow you to use 
resources to program your application windows. Thisis still true, 
however I have come across a method which allows MS Basic to 
use window resources as a guide for the window that will be used 
in Basic. This method is very simple and only requires three calls 
from the ToolL ib library. It does not extend the window creation 
capabilities, however. Languages which fully support the tool- 
box will usually allow you to create a window using the WIND 
(window resource) ID number. 

Now you can create your own window resources using 
ResEdit and Basic will read the resource and create a window 
looking like the one described by the resource. Well, usually. 
There are still those types of windows that Basic doesn't support 
such as the ones with rounded comers of different curvatures. 
ZBasic does support these other types and a similar method could 
be used to read the WIND resources from ZBasic. 

For now I'll explain what to do to implement this method. 
You might also get some ideas of other resources you could read 
and apply the same idea to. 

First off, in case you don't know how ResEdit can be used 
to create your own windows I will briefly explain by walking you 
thoughan example. Open up ResEdit and choose 'NEW' from the 
File menu. I chose to use a separate resource file (named 
"Window.rsc’) for this example just to be safe. You could use any 
file to store your resource in just like the library CODE resources. 
Next (with the new file open) open up a new resource by 
selecting 'NEW' from the File menu. Create a resource of type 
"WIND ' by selecting or typing the proper type when asked. 

At this point ResEdit gives you a default window which сап 
be sized and placed where ever you want it. The move the 
window drag it near the title bar just like you would move a 
window when using the Finder. To resize the window you drag 
the lower right corner of the window to the size you want. 
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WINDs OW.rsc 


ЕГІН Window 10 = 3041 from WINDOW.rs 


ұу 


CLE ET ETRE ERRARE E RERER nT er Ter renner rae rr renner rr ner rrr nn ера 


Now select Get Info from the File menu to adjust the 
window ID# if necessary. Usually you are safe to just use the 
number that ResEdit assigns the WIND resource. In this example 
I used 3041 through 3044 for the four windows that I created. 


You will have to create your own resources to use the example 
program, Besure to use the same ID numbers in the program that 
you use as your resource ID. 

There are two ways to view WIND resources with ResEdit. 
The first is graphically which is the mode you get when you first 
open a WIND resource. The second way is to display the WIND 
resource parameters as text. If you want different window types 
you can select Display text to show the actual window resource 
parameters. 

The ProcID is the parameter which indicates the window 
type. The ProcID numbers are shown in Inside Macintosh as: 
CONST documentProc = 0; 

dBoxProc = 1; 
pleinDBox = 2; 
altDBoxProc = 3; 


= Window 10 = 3041 from WINDOW.rs 


Dd Visible 


DJ goAwayFlag 
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noGrowDocProc = 4; 
rDocProc = 16; 


Since not all of these are supported by MS Basic the 
example program will ignore those that it doesn't understand and 
use the default document window. You could probably try this 
same method using ZBasic and be able to implement all of the 
features. Another way to view the resource would be to open it 
up as General instead of using OPEN in the File menu. Using this 
we can see how the WIND is organized. 

mem WIND 10 = 3041 from WINDOW.rsc 
$ |00 2E 00 OA 
00 00 01 00 


00 00 08 57 
772031 


00 RC 01 4E 
01 00 00 00 
69 GE 64 6F 


From this HEX representation of the WIND resource and 

Inside Macintosh (pg. 1-302) we see: 

$00 2E, the first two bytes represent the top of the window 
where HEX $00 2E = 46 decimal. 

the 3rd and 4th bytes represent the left of the window 
where HEX $00 0A = 19 decimal. 

the 5th and 6th bytes represent the bottom of the 
window where HEX $00 AC = 170 decimal. 

the 7th and 8th bytes represent the right side of the 
window where HEX $01 4E = 202 decimal. 

the 9th and 18th bytes represent the ProcID parameter. 

the 11th and 12th bytes represent the visible parame- 
t 


$00 BA, 
$00 AC, 
$01 4E, 


$00 00, 
$01 00, 


er. 
$01 00, the 13th and 14th bytes represent the goAwayFlag 


peremeter. 
$00 00 00 д0, the 15th through 18th bytes is the refCon 
parameter. 
$08, the 16th byte represents the length of the window 
title (the next 8 bytes) where $57 69 6E 64 6F 77 


20 31 is ‘Window 1' when converted via ASCII codes. 

The only thing left to finish the new resources now is to 
close the resource file and quit ResEdit. The example Basic 
listing below will read the resource file and store it in and array 
where the information can be used to create a window that looks 
the same as the one created in ResEdit using the standard MS 
Basic window command. This is accomplished with the aid of 
three ToolLib calls. The first is OpenResFile, used to open the 
desired resource file. The last is CloseResFile, used to close the 
resource file. The trick comes in using LoadArray to read in data 
from an open resource and place it in a pre-dimensioned array. 
Since the data that is read is not in the same format that Basic 
expects for variables, it is necessary to read each by and decode 
or convert the data to MS Basic variables which we сап use in the 
Window statement. The subroutine GetResWindow demon- 
strates which byte to peek to get the desired results. The variable 
pointer must be explicitly defined in each of the peek statements 
or the data may not come back correctly. You may only need to 
read back the parts that will be used in your program. 

Ап optional way of doing this would be to manually write 
down what the window size and type etc. after creating the 
window with ResEdit (then you wouldn't need to actually save 
the window resources) and then use these numbers to create your 
new window. This would make the Basic code shorter, but might 
not be quite as accessible to modification after it is compiled 
(provided you intend to compile your application). 


390 


As mentioned last month, there are still some serious 
problems with HFS and MS Basic. Until this is fixed, the use of 
resources is somewhat restricted. Since a compiled MS Basic 
application does not have an automatic way (a way in which the 
user doesn't have to be aware of what is going on) to find the 
volume which itself is located, we will have to live with the 
problem until Microsoft releases an improved version. (Sooner 
the better). 

‘WIND Resource Demo ®MacTutor™ 1987 By Deve Kelly 


Libname$="Hard Disk:Basic:MS ToolLib:ToolL ib" 
LIBRARY Libname$ 

WINDResname$="Hard Disk :MacTutor™:May87 :Window.rsc" 

WIDTH 40 

DIM a(40) 

FOR i=1 TO 4 

ID$23040* i 

CALL GetResWindowCWINDResneme$, ID%, top, lef t,bottom, right, 
ProcID, TitleLength, Title$) 

type= 1 

IF ProcID= Ø THEN type=1 

IF ProcID=1 THEN type=2 

IF ProcID=2 THEN type=3 

IF ProcID=3 THEN type=4 

WINDOW i, Title$, Cleft, top)-Cright, bottom), type 

PRINT "Tops ";top,"Left= ";left,"Bottoms ";bottom, "Rights 


"right 
PRINT "ProcID = ";ProcID 
PRINT "TitleLength = ";TitleLength 
PRINT "Title = ";Title$ 
PRINT "Click mouse to continue" 
WHILE MOUSEC02«» 1: МЕМО 
NEXT i 


‘full path name 


END 

SUB GetResWindow (WINDResname$, 10%, top, left,bottom,right, 

Ргос10, TitleLength, Title$) STATIC 

refs=0 

type$= "WIND" 

openresf ile WINDResname$,ref% 

loadArray ref%, ID%,aC 1), type$ 

top=PEEK (VARPTR( ac1)) )3256*PEEK (VARPTR(aC 1))+1) 

lef t-PEEKCVARPTRCaC 1))+2)*256+PEEK CVARPTR(aC 1) +3) 

botton-PEEK CVARPTRCaC 1))+4)*256+PEEK CYARPTRCaC 1))+5) 

right-PEEKCVARPTRCaC122*62*256*PEEK CYARPTRCaC122*7) 

ProcID-PEEKCVARPTRCaC 122*82*256*PEEK CVARP TRCaC 12249) 

TitleLength-PEEKCVARPTRCaC 1) + 18) 

closeResF ile ref% 

Titleg="" 

FOR i=1 TO TitleLength = 
Title$=Ti t 1e$*CHRSCPEEK CVARPTR(a( 1))+1+18)) Sel 


é fie Edit Search Run Windows 


Left= 10 
172 Rights 334 
0 


110 Left= 
Right= 


BiClick mou] Bottom= 240 
Е ProciD= 1 
TitleLength - 8 
ES Title = Window 2 
BI Click mouse to continue 
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Basic School 
Text Edit from MS Basic 


As you may recall from previous discussions about MS 
Basic, there are several statements in version 3.0 of the inter- 
preter and version 1.0 of the compiler which have not yet been 
documented. Well, at least these statements have not been 
documented by Microsoft. In fact, they are documented іп Inside 
Macintosh (and books like Macintosh Revealed ). The state- 
ments I refer to are all calls to the Macintosh Toolbox text-editing 
routines. Before this version of Basic text-editing was limited to 
whatever you could do with the Edit Field statement. The 
Macintosh text-edit routines provide basic text editing, with no 
added features. Some basic text edit capabilities include cut, 
paste, copy, insert, delete, and scrolling are provided. Word 
wrap, double-clicking to select words, inverse highlighting is 
supported. It allows you to edit a single font, style, and size 
(display only one at a time). It provides the basics of what full 
blown word processors provide. Text Edit does NOT support the 
use of more than one font or style, fully justified text, tabs and 
adjustment of spaces between words in the current system file. 
However, under the new system file for the Mac II and SE, 
multiple fonts and style are supported, but tabs and 32K limita- 
tions remain a problem. The new system file is scheduled to ship 
in May and should bring these new features to Mac Plus systems 
as well. A good review of text edit's capabilities is given in the 
Pascal multi-window example in the January issue of MacTutor. 

The Inside Macintosh Edit Records are automatically pre- 
pared by MS Basic when the EDIT FIELD statement is first 
defined. The Edit Record contains information which defines the 
complete Editing environment. You don’thave to know or worry 
about what goes on with the Edit Records to use the new calls. 
Each Edit Field has a handle (teHandle) which refers to the Edit 
Record. Microsoft has beefed up the EDIT FIELD statement so 
that when the Text Edit field is defined the text string no longer 
defaults to a selected state. Otherwise, your program may not 
have quite the appearance that you desire, especially if you are 
creating a text editor. 

In the text edit field, a character position is an index into the 
text. Position zero corresponds to the first character of the edit 
field. The selection range is indicated by a starting and ending 
index into the text. The text that will be highlighted when 
selected by the mouse is indicated by the start and end indexes. 
If the starting and ending position is the same then the position is 
indicated by the insertion point. The insertion point is the 
position where the characters will be inserted. 

There are 10 new calls which are already built into Basic. 
These 10 are only about half of the total number of routines given 
in Inside Macintosh . The routines which are not implemented 
are already provided for by using the EDIT FIELD statement in 
Basic. The statements NOT available are: 
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" é File ғай E 


Click mouse button outside of edit field or type .. 


This is the first string. Now is the time for all good men to come to the 
aide of their country end to show what they ere made of end it better 
not be suger and spice or anything nice, but puppy dogs tails and good 
‘ole American know-how. As you can see this text wraps nicely, but you 
went to hear a good one? The cerriage return doesn't work in this model 


How to do figure that? 


The Text Edit field has been created. (EDIT FIELD statement) 


TextEdit Buffer: ? 199660 204390 361 


Fig. 1 Edit Fleld Text Wraps! 


ТЕСТ ick TECopy TECut 
TED ispose TEGetText TEIdle 
TEInit TENew TEPaste 
TESetJust TextBox 


First a few words about some of the syntax used. The 
WINDOW(6) function is used to return the handle (same as 
teHandle) for the active edit field in the current output window. 
WINDOW (6) returns zero if the window has no active edit field. 
The SADD(<string-expression>) function returns the address 
of the first byte of data in <string-expression>. Note that this 
value is only valid until another string allocation of a new 
variable assignment takes place, since string allocations and 
variable assignments can cause existing strings to move in 
memory. The selection range referred to in some of the state- 
ments is the range of text which is selected in an edit field. Here 
are the new commands with a quick description of their use and 
syntax: 


TEACTIVATE 
Syntax: TEACTIVATE WINDOW(6) 


Description: TEACTIVATE displays the insertion point and 
highlights the selected text (unless the selection is the insertion 
point) in the text edit field specified by the WINDOW(6) 
function. Macintosh User Interface Guidelines indicate that 
when a window is inactive, the text selected in a text field should 
be inactive and the insertion point should be hidden. Use this call 
when your window is activated. Remember that text edit always 
works on the currently active grafPort; ie the SetPort result. See 
TEDEACTIVATE also. 


TECALTEXT 
Syntax: TECALTEXT WINDOW(6) 
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Description: TECALTEXT recalculates each line of text in the 
edit field indicated by the WINDOW(6) function. This call 
should be used whenever the number of characters per line of the 
edit field has been changed. 


TEDEACTIVATE 
Syntax: TEDEACTIVATE WINDOW(6) 


Description: TEDEACTIVATE hides the insertion point and 
unhighlights the selected text in the text edit field specified by the 
WINDOW(6) function. Macintosh User Interface Guidelines 
indicate that when a window is inactive, the text selected in a text 
field should be inactive and the insertion point should be hidden. 
Use this call when your window is deactivated. See TEACTI- 
VATE also. 


TEDELETE 
Syntax: TEDELETE WINDOW(6) 


Description: TEDELETE removes the text which has previ- 
ously been selected in the edit field indicated by the WIN- 
DOW (6) function. The text which is deleted is not recoverable. 


TEINSERT 
Syntax: TEINSERT SADD(string ), LEN (string ), 
WINDOW(6) 


Description: TEINSERT takes the specified string and inserts 
it at the insertion point of the edit field indicated by the WIN- 
DOW(6) function. Any selected text is not replaced by the 
newly inserted text. Use TEDELETE to delete selected text. 


TEKEY 
Syntax: TEKEY key , WINDOW(6) 


Description: TEKEY replaces the selection range with the 
character key typed at the keyboard. If the selection range is an 
insertion point then the character is inserted. All types of 
characters (normal and control characters) are inserted so your 
routine should filter out any unwanted characters. TEKEY re- 
draws the text as necessary. It is not clear if this can be used with 
an Edit field in Basic, since the Edit field statement prevents 
INKEY$ from allowing you to get single keystrokes from the 
keyboard. The only apparent way to get text typed by the user 
during an active Edit field statement is to use EDIT$, which 
returns the entire string contents of the text edit record. 


TESCROLL 
Syntax: TESCROLL horiz, vert, WINDOW(6) 


Description: TESCROLL scrolls the text within the edit field 
specified by WINDOW (6) by the number of pixels specified by 
horiz and vert parameters. Positive parameters move the text to 
the rightand down. Negative parameters move the text to the left 
and up. See Inside Macintosh for more information. 
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TESETSELECT 
Syntax: TESETSELECT 
WINDOW(6) 


selStart, selEnd, 


Description: TESETSELECT sets the selection range of the 
edit field text indicated by the WINDOW(6) function. The old 
text selection is unhighlighted and the text between selstart and 
selend is highlighted. Selstart and Selend can range from 0 to 
32767. If Selend is beyond the last character of text, the position 
just past the last character is used. 


TESETTEXT 
Syntax TESETTEXT SADD(string), LEN (string), 
WINDOW(6) 


Description: TESETTEXT changes the text string of the edit 
field pointed to by the WINDOW(6) function. The edit field 
will now point to the string set by the new string parameter. The 
selection point is set to the end of the new text. However, the text 
is not re-drawn. Follow this with an ERASERECT and the next 
function below, TEUPDATE. 


TEUPDATE 
Syntax: TEUPDATE VARPTR(rect%(0)), WINDOW(6) 


Description: TEUPDATE draws the text of the edit field 
specified by the WINDOW(6) function within the rectangle 
rect%. 


The call descriptions are somewhat brief. It will be useful to 
look at a few examples. Some of the new calls will probably only 
be used occasionally since the Basic Edit Field routines auto- 
matically provide some of the functions. The text edit demo 
program I have prepared will show some working examples of 
some of the text edit calls. The TEKEY, and TESCROLL, 
calls will be saved for a later column. Now you can write your 
text editor in BASIC (well, sort of)!! The DOUBLE-CLICK ME 
programs that come with the Basic interpreter use a few of the 
calls, the QnD (Quick-N-Dirty) editor demo (included with 
Basic) uses a few more of the calls. The problem with these 
examples is that they don’t make use of the ToolLib routines for 
creating scroll bars. Instead, they draw and manipulate their own 
set of scroll bars and window bars by drawing rectangles in a 
blank window and keeping track of them all. This seems to make 
things a lot more confusing than it has to be. This might be an 
indication that these demos were actually written before it was 
decided that the ToolLib routines would be included. If so, then 
it seems to me that Microsoft would have had plenty of time to 
document the text edit routines by now. As of this time, no one 
at Microsoft has sent me any information about the text edit calls 
which I had requested. If the QnD edit was written after ToolLib 
was slated to be included in MS Basic then it appears that the 
authors of QnD didn't yet know how to use the ToolLib Libraries. 
Atany rate, QnD will give you some ideas of ways to implement 
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a text editor. 


The Text Edit Demo will show you the effects of each call as 
youclick through each step by pressing the mouse button outside 
of the Edit Field. If you click inside the Edit Field (which is 
controlled automatically by Basic) you will be changing the 
insertion point or selecting and highlighting text, if you drag the 
mouse. If you type, characters will be inserted at the insertion 
point, and the text will wrap when it gets to the end of the line. 
More on this later. The demo will first create an edit field and put 
default text in it. Next you click the mouse button and the default 
textis replaced by anew string (set with the TESETTEXT call). 
The TEUPDATE call re-draws the edit field with the new 
string. Click the mouse again and the selection range is set up by 
the TESETSELECT call such that the text is selected from the 
lst up to the 6th character. Another click of the mouse and the 
TEDELETE call deletes the selected text. The next clicks 
deactivate and activate the edit field followed by text inserted by 
the TEINSERT call. Most uses of these calls are demonstrated 
by this demo. 


Word Wrapping Edit Fields 
by 
David E. Smith 


Normally, Basic sets up an Edit Field with a very large 
destination rectangle and with the text edit field crOnly set to 
FFOO, a negative value. This indicates that lines will only break 
at a Carriage return. Hence when you type in the Edit Field, the 
text never wraps at the end of the line as you would expect from 
normal use of text edit functions in other languages. Many people 
have been frustrated at trying to get text to word wrap in Edit 
Fields (see letters column this month fora few such frustrations! ). 
In order to get text to wrap, the destination rectangle must be the 
same size or smaller than the view rectangle, which Basic sets 
equal to the Edit Field rectangle. Also the crOnly field must be 
positive. In our demo program, we call a subroutine called Wrap, 
which pokes the proper values into the text edit record so the 
destination rectangle is changed and the crOnly field is changed. 
Hence, if you type in the demo program, you'll see that when you 
get to the edge of the Edit Field box, the text does word wrap 
properly. However, there is a penalty for this. 


With word wrapping enabled, Basic no longer processes or 
returns Carriage returns in the Edit Field, even when you set the 
type parameter to indicate that it should process carriage returns. 
Whatever mechanism Basic uses to intercept and process control 
characters in an active Edit Field apparently will not process 
carriage returns if the crOnly field is positive. You can try this 
with the demo. As you type (assuming you type at the end of the 
text), each character will be displayed on the Edit Buffer line. If 
a carriage return is received, then the program will print “СК” 
there. But with the subroutine call to Wrap, you'll never see а СЕ. 
Now if you remark out the Wrap subroutine call, then carriage 
returns will be returned properly, but of course then the Edit Field 
won't wrap text to the view rectangle! This seems like a design 
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bug in Basic as there is no obvious correlation between the text 
edit record set-up and whether or not carriage returns get filtered 
from the Edit Field. 


Peeking at the text edit record and changing it's fields can be 
a very interesting pursuit. To do this, you need to get the handle 
to the text edit record. This is returned with the WINDOW(6) 
function. You can store this in a double precision variable as 
shown in the program listing under the TextEdit subroutine. 


nyHendle?* = WINDOWCO) 


On our Text Buffer line, we've printed some important 
debugging information. The first large number is the teHandle to 
the text edit record. The next number is the address of the text edit 
record itself. The final small number is one of the text edit record 
fields, ie the length of text in the buffer. As you type, you'll see 
this number increment. To dereference the handle, we use the 
PEEK function: 


рігі = PEEKCmyHandle#+3) 
ptr2 = PEEK(nyHandle'tt*2) 
ptr3 = PEEK(myHandle®+ 1) 
ptr4 = PEEK(nyHandlet*g) 


This returns the four individual bytes at the handle. They now 
have to be re-constructed into the master pointer: 


ptr® = (ptr3*65536!)) + Cptr2*256) + ptr 


Now we have the address of the text edit record itself. This 
address is valid as long as we don’t do anything that would move 
things in memory, like call a toolbox routine. Now we can peek 
at individual text edit record items, like the length: 


telength1 = PEEK(Cptr#+6 1) 
telength2 = PEEK(ptr#+66) 
telength = telength2 * 256 + telength! 


Once we've identified the text edit record, then our Wrap 
routine can poke new values into the destination rectangle and the 
crOnly field. The address of the crOnly field will be ptr#+72. The 
address of the destination rectangle is ptr# since it is the first field 
in the record. The address of the view rectangle, which is the 
second item in the field is ptr#+8. Rectangles are eight bytes, so 
if we poke the destination rectangle field with the view rectangle 
field, then the two will be the same, and the text will wrap. A little 
for next loop does this for us in the Wrap subroutine. To find the 
address of other items in the text edit record, just add up the size 
of each field. A rectangle is 8 bytes; a point is 4 bytes, as are 
pointers and handles; an integer is two bytes. Starting at zero, it 
is easy to determine the offset of each field in the record from the 
definition in Inside Macintosh. 


Can you really make a text editor? It doesn't look too good, 
even with these new routines. The problem is, you don't really 
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have an honest event loop, so how do you get keystrokes. The 
only events Basic lets you have are menu events and dialog type 
events. Key events are intercepted by Basic. For example, if you 
have an active Edit Field as we do in this example, how do you 
get the actual single character last pressed? INKEYS$ is ignored 
when the Edit Field is active. The only option seems to be the 
EDITS$ statement, which returns the entire edit field contents. So 
youdon'treally havea text editor if you can't process keystrokes. 
Remember, TEKey only inserts characters into a text edit 
record, it doesn't poll the keyboard. That is supposed to happen 
during an event loop, but Basic only lets you see certain events. 
If you find some more information on this subject of using MS 
Basic 3.0 with text edit, share it with our MacTutor audience. 

" é File Edit ? 


Click mouse button outside of edit field or type ... 
Т һе second string. (replaced old string) 


The text has been selected... selection range k 
is from before character 1 until before character 6. (TESETSELECT call) 


TextEdit Buffer: ) 199860 204120 45 


Fig. 2 Making a selection 


‘Text Edit Demo 
‘By Dave Kelly 
'teRec Wrap by Dave Smith 
‘@MacTutor 1987 


OriginalEditString$-"This is the first string.” 
endofstring-LENCOr iginalEdi tStr ing$) 

' Set up rectangle for TEUPDATE са11 
rect$(0)-20:rect8( 1)= 10: rect%(2)=200 :rect$ (322460 


WINDOW 1,^"Text Edit Demo^,(15,402-(495,330),2 

EDIT FIELD 1,0riginalEditString$, C10,202-C460,200),6, 1 

PRINT “Click mouse button outside of edit field or type ..” 

LOCATE 15,1 

PRINT “The Text Edit field has been created. (EDIT FIELD 
statement)” 

LOCATE 17,1:PRINT “TextEdit Buffer :” 

oldkey$="" 

GOSUB wrap: REM make textedit wrap to view rectangle 

TESETSELECT endofstring+1,endofstr ingt1,WINDOW(6) 

GOSUB eventloop 


‘Set the edit field text to a new string 

NewEditString$-"This the second string. (replaced old string)” 

TESETTEXT SADD(NewEditString$), LEN(NewEditStringf), 
VINDOWCO) 


‘Re-draw the edit field (needs to be re-drawn after setting 
new text).. 

ERASERECT VARPTR(rect%(@)) 

TEUPDATE VARPTR(rect%(0)),WINDOWC6) 

LOCATE 15,1 

PRINT “The Text Edit field has been set to & new string 
(TESETTEXT call).’ 

GOSUB event loop 
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‘Set the selection range.. 

TESETSELECT 1,6,WINDOW(6) 

LOCATE 15,1 

PRINT “The text has been selected. selection range’; 
STRING$(50," ~) 

PRINT “is from before character 1 until before character 6. 
(TESETSELECT call)’ 

GOSUB eventloop 


‘Delete the selected text.. 

TEDELETE WINDOWMCO) 

LOCATE 15,1 

PRINT “The selected text has been deleted. (ТЕПЕ, ЕТЕ 
call)”; STRING$C30," 4) 

PRINT STRING$(C 150,” ”) 

GOSUB eventloop 


'De-activate the edit field.. 

TEDEACTIVATE WINDOW(6) 

LOCATE 15,1 

PRINT “The text has been deactivated CTEDEACTIVATE call)’ 
GOSUB еуепі1оор 


'Re-activate the edit field... 

TEACTIVATE WINDOWCO) 

LOCATE 15,1 

PRINT “The text has been activated (TEACTIVATE call)’; 
STRINGÉCIO,^ *) 

GOSUB еуепі1оор 


‘Insert new text at the insertion point.. 

TextToInsert$-"-This text was inserted-^ 

TEINSERT SADD(TextToInsert$), LENCTextToInsert$), WINDOWCO) 

LOCATE 15,1 

PRINT “Text has been inserted at the insertion point. CTEIN- 
SERT call)” ;STRING$(20,” *) 

GOSUB eventloop 


quit: 
EDIT FIELD CLOSE 1 
CLS: END 


event loop: 

WHILE MOUSE(O)«> 1 

GOSUB TextEdit 

key$-EDIT$C1) 

IF key$óoldkeu$ THEN GOSUB processtext 
oldkey$=key$ 

WEND 

RETURN 


processtext: 

char typed$=RIGHT$(key$, 1) :REM how do you get last cher 
typed? 

LOCATE 17, 18 

PRINT SPACESCA); 

LOCATE 17, 18 

IF OIX DUDEN IURE CIO THEN PRINT chartyped$ ELSE PRINT 


RETURN 


TextEdit: 

nyHendle*-WINDOWC6) 

LOCATE 17,24:PRINT myHandle* 

ptr 1=PEEK CmyHandle*+3) 

ptr2=PEEK (nyHand1e't*2) 

ptr3=PEEK CmyHandle*+ 1) 

ptr4=PEEK CmyHendle?t 40 ) 
ptrz(ptr3*(65536!)) + Cptr2*256) + ptr1 
telength! = PEEK(ptr®+61) 
teLength2=PEEK(ptr®+68) 

teLength = teLength2*256+te length! 
LOCATE 17,35:PRINT ptr! 

LOCATE 17,45:PRINT teLength 
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RETURN " é File Edit Ё 


wrap: Click mouse button outside of edit field or type ... 
GOSUB TextEdit : REM get teRec address This the second string. (replaced old string 
REM poke new values in teRec 

crOniyAdd#=p tr®+72 

сгоп1џ&=0 :РОКЕ crOnlyAdd#,® :REM turn OFF cronly 

FOR 1=0 TO 7 

POKE ptr#+8+i,PEEK(ptr#+i>: REM dest rect = view rect 


NEXT i 
TECALTEXT WINDOW(6): REM re-do line endings 
RETURN 


The Text Edit field has been set to a new string (TESETTEXT call). 


TextEdit Buffer: ) 199860 204120 45 


55222) Fig. 3 Set new text 
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Basic School 


Almost a Fonts Menu for PCMac Basic 


The months seem to be flying by and the major improve- 
ments to Basic that I have been waiting for are still not released. 
There are some improvements whichare worth mentioning. This 
month I speak of improvements to the PCMacBasic compiler 
(now version 2.01). Ithas been several months since I last spoke 
of PCMacBasic. The authors were quite busy toward the end of 
last year finishing up other projects so there wasn't much prog- 
ress to talk about. Now there have been some noteworthy 
improvements, although there are still some weak areas which 
can and will probably be corrected if we give them enough time. 

The firstimprovement that I noticed was the manual now has 
a spiral binding. The previous manual I had was stapled and not 
easy to handle. Documentation style has not changed much, but 
there has been a little more explanation added to some sections. 
I still have trouble finding things in it (there is no index). Since 
the manualis splitinto two sections, General Information and А1- 
phabetical List of Basic Commands, there are two separate sets 
of page numbering (one for each). If you don't know this you 
could get lost easy if you are looking in the wrong half of the 
book. Most every section contains more information than was 
presented in the old manual. However, I felt that a novice user 
might have trouble understanding somethings the first time 
through. 

LINE LABELS SUPPORTED 

A major improvement to PCMacBasic is the ability to use 
line labels (as opposed to line numbers) in your program source 
code. If the Line Labels box is checked in the Compile dialog 
box, your Basic program may have alpha-numeric labels for lines 
as well as integers. If the Line Labels box is checked, line 
numbers are considered to be labels of digits. Up to 38 digits are 
allowed and compared. (When the Line Labels box is not 
checked, line numbers must be 1 to 65534.) When compiling, 
each line label is mapped to a line number when it is first 
encountered. That number is used in place of the label by the 
compiler. An alpha-numeric label is mapped to the highest 
number already used plus one. If the highest number, 65535, has 
already been used, then the highest number available is used. 

When the Line Label feature is used, all line labels, even all- 
digit labels, are stored in the Symbol Table while compiling. This 
is slower and uses more memory for each label than compiling 
with the Line Labels feature turned off. Programs with a number 
on each line should be compiled with Line Labels off, or the 
numbers should be removed from lines which are not entry 
points! 

HFS SUPPORT 

HFS support has been improved. The FILES$ functions 
return the full path names as it should. However, The 
FILES$(PROGRAM) function returns only the name of the 
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program file and not the full path name even when the default 
path name is another volume. This is better support than MS 
Basic provides, but it would be nice to be able to find out where 
your application is located. (Note:see June 1987 MacTutor, page 
8, for the solution for MS Basic). My SCSI Hard Disk turns out 
to have a volume number of -1 which is not mentioned in the 
manual (The manual states that hard disk boot volume is drive 
number 3, pg. 23. This may refer to Apple HD20????). 
TOOLBOX ACCESS 

The (improved) PCMacBasic manual now has a better 
explanation of how to call the toolbox from PCMacBasic. The 
remainder of this column will discuss the *method to the mad- 
ness’ of calling the toolbox. 

It would certainly help you if you have had some experience 
working with an assembler at some time in your life. It turns out 
that you don't need to know how to do assembly to call the 
toolbox if you know just a few basic assembler codes. Toolbox 
calls in PCMacBasic are made by way of the USR function/ 
statement. This statement is used for calling routines written in 
other languages. 

At this point it is important that you have a copy of Inside 
Macintosh to refer to. To understand the toolbox calls listed in 
Inside Macintosh you need to understand the data types used in 
the calls. The Pascal data types are: 


Type Size 
INTEGER 2 bytes 
LONGINT 4 bytes 
BOOLEAN 1 byte 
CHAR 2 bytes 
SINGLE (or REAL) 4 bytes 
DOUBLE 8 bytes 
EXTENDED 10 bytes 
COMP 8 bytes 
STRINGIn] п+1 bytes 
Signed Byte 1 byte 
Byte 2 bytes 

Ptr 4 bytes 

Handle 4 bytes 


Record or Array 2 or 4 bytes 
VAR parameter 4 bytes 


Most toolbox calls will use the INTEGER or STRING[n] 
types of parameters. There are other types which are defined by 
Pascal which are made of the primary types above. Let's take a 
look at an example: 

themenu!=USR ~ DC.W $4931^ (304, title$) 

In this example the USR function is used to call NewMenu 

(toolbox function). The USR function will insert $A931 at the 
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point in the program where this statement appears. The *DC.W" 
is an assembler pseudo-op which instructs the compiler/assem- 
bler what to do. (NOTE: A SPACE MUST PRECEDE THE 
DC.W). Page 11 of Appendix F (PCMacBasic manual) lists the 
valid pseudo-op codes. Unless you like assembly language you 
probably won't have to remember more than a couple of these 
(DC.W being the most frequently used in toolbox calls). Macro 
names may be substituted for the assembler pseudo-op “DC.W”. 
The PCMacBasic manual states that all you have to do is “сору 
the macro definitions from the appropriate files for the assembler 
you are using into the BASICMacConst file". This is stupid!! 
First of all, I'm using PCMacBasic compiler not somebody's 
assembler! The compiler should be smart enough to take care of 
this for me! Besides, they didn't even include the assemble 
macro definitions in a file on the PCMacBasic disk to include in 
the BASIC MacConst file or directions on how to add my own. 
They're assuming that I know how (or want to) program in 
assembly. In fact, I like Basic because I don’t have to go through 
all the trouble that assembly provides. Well, at least PCMacBa- 
sic provides a way to do the calls I want even if it does make it 
harder than it should be. If you have to use "DC.W" then you will 
have to look up the appropriate address for the macro name in 
Appendix C of Inside Macintosh vol. 3 . 

Refer to page 1-351 of Inside Macintosh to find the parame- 
ters that must be passed to the toolbox function. There you will 
find the first parameter is menuID which is an INTEGER type. 
INTEGER types are passed directly to the stack . In the example 
304 isthe menuid which is passed directly to the stack. A variable 
such as Menuid% could have been used in place of 304 (provided 
that Menuid% is set equal to 304 before using the NewMenu 
function. The INTEGER type, as you can see, is simple to use. 
Life starts to get tougher when other types must be passed. 

The main thing to keep in mind here is how many bytes need 
to be passed and how many bytes each PCMacBasic variable 
uses. The PCMacBasic manual covers this very briefly on page 
4-6. Fortunately, the variable types are similar to those used in 
MSBasic so it might be easy to guess. 

PCMacBasic Size 


Integers 2 bytes 

single 4 bytes 

double 8 bytes 

strings 4 byte descriptor 
records VARPTR 


Integers are 2 bytes, single precision are 4 bytes, double 
precision аге 8 bytes. Strings are stored in the heap with a 4 byte 
descriptor. Integers and single precision may be passed directly. 
When calling Pascal records you have to use VARPTRS, since 
Pascal passes addresses for anything over 4 bytes rather than the 
actual data on the stack. 

. . Now back to the example. The menuTitle parameter is type 
50255 (according to Inside Macintosh) . Str255 represents a 
STRING type with up to 255 characters. The Pascal string is 
consists of a length byte and the string information following it. 
Therefore, the menu title must be converted to a Pascal string 
before it can be passed to the NewMenu function. The 
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PCMacBasic suggests a couple of ways to do this. The easiest is 
toconcatenate the length to the beginning of the string as follows: 


titleg=chr$Clen( “Fonts” ))+“Fonts” 


The problem with this method is that it is really much slower 
than it should be. Page 4 of Appendix C (PCMacBasic manual) 
gives alternative methods. This is one of the weak parts of the 
PCMacBasic Compiler’s methods for using the Mac toolbox. I 
feel that the call itself should take care of this type of conversion 
for you. It just complicates the process. It would be better if there 
were a Basic string to Pascal string conversion routine (both 
directions) built into PCMacBasic. 

Since most (if not all) of the Quickdraw routines are outlined 
in Appendix C (mostly passing all integer types), I'll refer you 
there for more examples which pass integers. Remember you 
can't use macro names unless you define them first. One of the 
best things about PCMacBasic is that the toolbox calls are com- 
pletely compatible with all of the PCMacBasic command set. 
That's not like some basics which won't let you mix quick draw 
with their own graphics commands (or limit their use) and won't 
give you handles and pointers to their own menus and controls so 
you could use them from your own toolbox calls. 

Another tricky conversion example: During my studies of 
PCMacBasic's toolbox calls I had trouble in converting a pa- 
rameter of type ResType for use in a call. The solution isn't 
readily found (it's not documented) in the PCMacBasic manual 
although it is consistent with the way that the USR statement 
works. Try the AddResMenu call for example. Ilike this one. In 
fact this is a call that ZBasic and MSBasic still can't do properly. 
Page 1-353 of Inside Macintosh shows the format for the 
AddResMenu call. All that is needed is the menu handle and the 
resource type and the call searches all open resources of the type 
and appends the names to the menu. Simple! Well, it turns out 
that if you use "FONT" as the resource type passed that the 
routine doesn't find the FONT resources. IF you convert to a 
Pascal string by adding the length byte at the beginning of the 
string it still can't find the resources. The key comes in realizing 
that ResType is a packed array [1..4] or CHAR. This Pascal lingo 
means that itis four characters (nota string). Well, remember that 
each character takes up one byte (that’s 4 bytes total). That means 
we need to get 4 bytes transferred to the stack. We know that 
integers will transfer 2 bytes so by defining two integers we are 
able to transfer 2 characters in each. Here is when you need to 
think about hex representation of numbers fora moment. We are 
trying to put “FONT” on the stack. That converts to 70797884 
in decimal (ASCII code) or 464Ғ4Е54 in hex. Therefore the first 
integer should be F1%=$464F and the second F2%=$4E54. 
Convert this to decimal to get F1%=17999 and F2%=20052. 
Now plug into the call: 


USR ~ DC.W $494D" Cthemenu! ,F2%,F 1%) 


realizing that the integers will be pull off the stack with last 
byte on is the first byte off (LIFO). Personally I would like to be 
able to just enter the string “FONT” and have statement work. 
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The PCMacBasic calls are not actually built in to the compiler 

(you insert them yourself). I consider this a sort of a kludge 

although very effective if you realize what is going on. 
RESOURCE FILES 

A few words about resource files: If you want your program 
to function like a true Macintosh application then you must use 
a resource file. If no resource file is specified then PCMacBasic 
will use the demo resource file named PCDemoR. It contains a 
sample set of resources that will keep the applications happy 
while your program is running. To create your own resource file, 
Irecommend making acopy of the PCDemoR file and modifying 
it to meet the needs of your own application. The Resource 
Compiler is documented in Appendix F of the manual. This is the 
same Resource Compiler as used in McAssembly compiler from 
Signature Software. The legal pseudo-op codes are defined in 
appendix F along with details on the format of the various 
resources that are used. 

In the sample program I have modified the resource file 
slightly to customize it for this program. I stripped out some of 
the error code stuff so as to save some space but your may want 
to keep it in your own file. 

The first part of the resource file that you will want to 
customize is the program signature. This string is inserted in the 
application resource file to give the version number and appli- 
cable information. Next the menus are declared. The Apple 
menu may be deleted from the resource file if you don't want desk 
accessories available to your application. Desk accessories will 
automatically be loaded (like it or not). The File menu items may 
becustomizedas you like. The Edit menu is set up in the standard 
Edit menu format and should probably be left as is for most 
applications. Other menus should be added from this point on. 

The next resources are used for various dialog boxes used for 
debugging and for the About dialog box. Next are default 
controls and windows. 

You may want to use your own custom icon for the applica- 
tion and files created by the application. Refer to previous issues 
of MacTutor for tutorials on adding icons to your applications. I 
recommend that you use ResEdit to copy the hex representation 
of the icon and the past it into the resource file and format it as 
shown in the sample resource files. 

The runtime configuration resource is used by PCMacBasic 
to set default attributes. Don’t mess with these unless you either 
know what you are doing or don’t care if you mess something up. 

The FREF resource defines the file id numbers for the 
application and the document file. Note that the signature I used 
in the sample is PROF which was declared toward the beginning 
of the resource file and is used in the bundle resource so that the 
application’s icon will be displayed properly. 

DISASTER STRIKES! 

OK, now you are probably wondering why the sample 
program doesn’t do anything. Well... it turns out that 
PCMacBasic has some problems that I didn’t know about until 
the very last few minutes of writing thiscolumn. The problem is 
that there is no way to trap the font items which we have so 
carefully read in using the AddResMenu statement. It turns out 
that the problem exists for all menus created dynamically from 
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within our program. 

Page 32 of the Alphabetical List of BASIC Commands 
section of the manual gives the explanation, in very fine print I 
might add. It states that the “runtime allocates space for as many 
function keys as you put in the resource file so nothing is wasted”. 
Menuevents can only beread by the ON KEY function. ON KEY 
was designed to simulate function keys used in IBM PCBasic. As 
long as the menu is defined in the resource file the runtime code 
of the compiler will allocate space for the ON KEY function. I 
suppose that if you know how may items will be in your menu you 
could define adummy menu with dummy items which you could 
later change. This “dummy” method is only for “dummies”. 
Another PCMacBasic user set up an event loop with GETNEX- 
TEVENT and trapped the menu as you would in PASCAL (or 
some other superior language). If you plan to go to all that trouble 
then it would be better to just write your application in PASCAL 
to begin with. 

The bottom line is that if you need to dynamically define 
your menus then PCMacBasic is NOT for you. However, as long 
as your program will only use the menus defined in the resource 
file you should be able to get by just fine. PCMacBasic is still the 
only choice for porting Basic programs over from the PC to the 
Macintosh. Until Pterodactyl Software decides to the ON KEY 
command to correctly return both a menu ID and a menu item ID, 
this problem will remain. As aresult, like all the other Basics for 
the Mac, there is still no Basic which adequately provides both 
for the complete supprt of the Mac user interface, and the high 
level of use of the Basic language at the same time. 


REM PCMacBasic Toolbox Sample 

REM ©MacTutor 1987 by Dave Kelly 

Stert 

break on 

ERROR OFF 

F182256*ascC^F ^)*ascC*0^) 

F28z256*ascC"N^)*ascC ^T^) 
Fonttitle$=chr$Clen( “Fonts” ))+“Fonts” 

themenu!=USR 4 DC.W $A931” (304, Fonttitle$) :КЕМ NewMenu 
USR * DC.W $494D" Cthemenu! ,F2%,F 1%) : REM AddResMenu 

USR ~ DC.W $4935" Cthemenu!,0) : REM InsertMenu 

USR * DC.W $4937^":REM _DrawMenuBar 

xZ=USR ~ DC.W $4950" Cthemenu! ):REM CountMI tems 

ERROR ON 

LOCATE ,,,1,1:REM Get rid of stupid black carret when program 
closes. 

print^There ere ";x$;^ items in the ‘Fonts’ menu” 

on keyC1) gosub quit 

Loop 

goto loop 


quit 
BEEP : END 


; 
; Resource File For Basic Program 

‚ 

; some equates we'1] need: 

chk equ $12 jascii for check mark character 


visible equ $FFFF ;TRUE boolean 
invisible equ 0 ;FALSE boolean 
nogoaway equ 0 ;FALSE boolean 
goaway equ $FFFF ^ ;TRUE boolean 
button equ 4 ;DITL BUTTON 
chkbox equ 5 ;DITL CHECK BOX 
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radio equ 
stattext equ 
editxtds equ 
iconitem equ 


6 з ОТТ RADIO BUTTON 

8+128 іт STATIC TEXT (DISABLED) 
16+128 — ;EDIT TEXT DISABLED 

32 ICON in dialog box 


7 
; Signature of program 


(С PROF, 2 


TEXT *"PCMacBasic Demo Version 1.0 May 23, 1987" 


1] 
; Apple menu 


$$ MENU, 1,4 
0,0,0 
$FFFFFFFB 

* /$ 14” 

2 


About this program 


0, 


0,0 


д 


0,0,0,0 


‚ 
; Files menu 


9 


Menu ID 1 

Placeholders 

enable mask - 2 disebled 

menu title = epple char 

iwo items in this menu 

item 1: 

е the menu item 

no icon, no keybd equivalent 

no marking char, text style = plain 
item 2: 

the menu item 

no icon, no keybd, no mark, plain text 


$$ MENU, 302, 4 Menu ID 302 
0,0,0 Placeholders 
$FFFFFFFF enable mask - none disabled 
Files menu title 
1 three items in this menu 
у item 1: 
*Quit^ 
0,0 no icon, no keybd equivalent 
0,0 no marking char, text style = plain 
; Edit menu 
$$ MENU, 301, 4 Menu ID 301 
0,0,0 Placeholders 
$FFFFFFF9 enable mask - ist & 2nd disabled 
Edit menu title 
6 six items in this menu 
item 1: 


“Cen’t Undo” 
9,0,0,0 
char, text style = 


д 
@ 


0,0,0,0 
. 


a 


д 
"Cut" 
0,'X^,0,0 


"Copy" 
0,'C^,0,0 


; 
“Равіе” 
0,'V^,0,0 


; 
*Clear^ 
0,0,0,0 


4 STOP or apple/pe 
$$ DITL,302,32 
5 


=. 


the menu item 


no icon, no keybd equivalent no marking 


plain 

item 2: 

the menu item 

no icon, no keybd, no merk, plein text 
item 3: 


no icon, no keybd, no mark, plain text 
item 4: 
the menu item 
no icon, keybd, no mark, plain text 
item 5: 
the menu item 

no icon, keybd, no mark, plain text 
item 6: 
the menu item 
no icon, keybd, no mark, plain text 


riod dialogue list 


Dialog item list, ID = 302, ATTR=32 
5 items in list 


item 1: 
hendle holder 
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50, 175,65, 190 
chkbox 
ее 


“ 
д 


0 

50,200 65,330 
StatText 
“Quit” 


50,35,65, 165 
StatText 
“Continue” 


д 


0 
10, 10,30, 400 
StatText 


display rectangle 
item type 


item 2: 

handle holder. 
display rectangle 
item type 

the item 


item 3: 

handle holder 
display rectangle 
item type 


item 4: 

handle holder 
display rectangle 
item type 

the item 


item 5: 

handle holder 
display rectangle 
item type 


“Program interrupted in line number 


; fatal error dialogue list 


$$ DITL, 400,32 
5 


) 

0 

10, 100,30,400 
StatText 


Dielog item list, 
5 items in list 


item 1: 

handle holder 
display rectangle 
item type 


“Fatal program error’ 


8, 40,25 


Q~. 


25,35,40, 165 
StatText 
“Restart” 


7 


0 

40, 10,55, 400 
StatText 

“Error 70 in Line 


0 
55, 10,70, 400 
StatText 


qe) 


item 2: 

handle holder 
display rectangle 
item type 


item 3: 

handle holder 
display rectangle 
item type 

the item 


item 4: 

handle holder 
display rectangle 
item type 

Number 71” 


item 5: 

handle holder 
display rectangle 
item type 

the item 


; invalid keyboard entry alert list 


$$ DITL, 301,32 
3 


М 


0 
80,200,97,310 
button 

“I’m sorry !^ 


Dielog item list, 
3 items in list 


item 1: 

handle holder 
display rectengle 
item type 

the item 


747 {ће item 


ID = 400, ATTR=(32) 


the item 


the item 


ID = 301, ATTR=(32) 
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Ў item 2: 

0 handle holder 

38, 78,58, 455 display rectangle 
StatText item type 

“Invalid input in line number ^1^ the item 
р item 3: 

0 hendle holder 

50,25,70, 455 display rectangle 


StatText item type 
“Please start over from the beginning.” ;the item 


; ‘About’ Dialog List 


Dialog item list, ID = 300, ATTR=(32) 


$$ DITL,360,32 
3 3 items in list 


| item 2: 

0 handle holder 

30,25,50, 455 display rectangle 

StatText item type 

“About this program ..” the item 
А item 3: 

0 handle holder 

50,25,70,455 display rectangle 

StatText item type 

“This is а sample PCMacBasic program.” ;the item 
) item 4: 

0 hendle holder 

70,25,90, 455 displey rectangle 


StatText item type 
^"eMacTutor 1987, by Deve Kelly” ;the item 


; ‘About’ Dialog Box 


$$ DLOG,309,32 dialog, ID = 300, ATTR=32 


100, 15,258,495 ^ bounds rectangle 

1 type = modal dialog box 
visible initial state 

nogoaway no close box 

0 ref con 

300 resc ID of DLOG’s item list 
| no title 


; Function Key Dialog Box 


$$ 0L06,521,32 dialog, ID = 581, ATTR=32 
45, 15,300, 495 bounds rectangle 
1 {уре = modal dialog box 


visible initial state 

nogoaway no close box 

0 ref con 

501 resc ID of DLOG's item list 
| no title 


; Debugger Dialog Box 


$$ 0106,650, 32 dialog, ID = 650, ATTR=32 


100 ,60,280, 450 bounds rectangle 

1 {уре = modal dialog box 
visible initiel state 

nogoaway no close box 

0 ref con 

650 resc ID of DLOG’s item list 
| no title 


; invalid keyboard input alert box 
$$ ALRT,301,32 alert, ID = 301, ATTR=32 


100,15,210,345 bounds rectangle 
301 resc ID of DLOG’s item list 


400 


$7655 stages 
; BASIC default Window 


$$ WIND, 300, 4 


40, 10,325,500 

0 type of window 
visible 

goaway 

0 refcon 
Untitled title 


; Vertical scroll bar for WIND 300 


$$ CNTL, 300 

20 , 408,220, 416 

@ initial value 
Invisible 

12000 тах value 

Ü min value 

16 scroll bar 

0 refcon 


“vertical scroll Баг”  ;title 


; Horizontal scroll ber for WIND 300 


$$ CNTL, 400 
200 ,20,216, 400 
Ü initial value 


Invisible 

12000 nax value 

0 min value 

16 scroll bar 
0 refcon 


“horizontal scroll bar” ;title 

; Cursor 

$$ CURS, 300, 4 

$0 1801470,$26482644,,$ 12401249, $6809980 1 
$88024002,$20022004, $ 10040808, $04080408 
$00000000,$00000000 , $00000000 , $00000000 
$00000000 ,$00000000 , $00000000 , $00000000 
$0008 , $0008 


; Professor Mac Icon & Mask for Program 
$$ IcNe, 128 

$00000000,$00000000,$00000000 , $00010000 
$200F 8000 , $00 1FE000 , $003FF800 , $00 7TFFEO0 
%00ҒҒЕҒ00,%0 1FEFF00, $0 1FFBEO0 , $00FFECOO 
$005ЕЕЕ@@ , $0087F000 , $0089E 480 , $008445CO 
$00800480 ,$008005C0, $00^02480, $00BFE 400 
$0090C508 ,$00400895,$00201095 , $00 ІҒЕ000 
$00 102000 , $00 1FE000,$0060 1800 , $0 1800600 
$02 186 100, $04C30C80,$04000080 , $0 TFFFF80 
$00000000 ,$00000000,$00000000 , $00070000 
$000F 8000 , $00 1FE000, $003FF800 , $00 TFFEO0 
$OOFFFFOO, $0 IFFFFOO, $0 ІҒЕҒЕ00, $00FFFCOO 
$00 TFFE00,$00FFFDOO,$00FFFCB80,$00FFFDCO 
$00FFFC80 , $00FFFDCO, $00FFFCB80, $00FFFCOO 
$00FFFODB,$007FF895,$003FF095, $00 ІҒЕ000 
$00 1ҒЕ000, $00 1ҒЕ000, $00 7FF800 , $0 ІҒҒҒЕ00 
%03ҒҒҒҒ00,%07ҒҒҒҒ80,%0ТҒҒҒҒ80,%ТЕҒЕҒ80 


Window, 10=300, attr=4 


Lom 


con 


; Document Icon and mask for Document Icon 


$$ ICN", 129 

$00000000 ,$TFFFFFB0, $403FFD40 , $40 TFFD20 
$40FFFD 10,94 IFFFDOB, $43FFFDFC, $4TFFFCO4 
$4FFEFFFC, $5FFDO IF4, $4FFEFEGA , $47FFFFC4 
$4 IFFFFA4, $423FFF94, $440FFEO4 , $4463F CBC 
$44FOF894, $44C830AC, $44000004 , $45 18C4AC 
$457DF 494, $45FFFCAC, $44FDF894 , $4438EQAC 
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444000084, $43FFFFO4, $47FFFF84, $4С0000С4 
$5 18CCC24, $60000014, $TFFFFFFC, $TFFFFFFC 
$00000000 ,$7FFFFFB0, $TFFFFFCO, $7FFFFFED 
$7FFFFFFO, $7FFFFFFB,$TFFFFFFC, $7FFFFFFC 
$7FFFFFFC, $7FFFFFFC, $7FFFFFFC, $7FFFFFFC 


$7FFFFFFC, $7FFFFFFC, $7FFFFFFC, $7FFFFFFC 
$7FFFFFFC, $7FFFFFFC, $7FFFFFFC, $7FFFFFFC 
$TFFFFFFC, $7FFFFFFC, $7FFFFFFC, $TFFFFFFC 
$TFFFFFFC, $TFFFFFFC, $7FFFFEFC, $TFFFFFFC 
$TFFFFFFC, $7FFFFFFC, $7FFFFFFC, $7FFFFFFC 


; Runtime Configuration for Macintosh 


[t CFI6,301 


; SCREE 


7 
7 
* 
7 
Ф 
д 
9 


N buffer & Update method 
2 = Text buffer with attributes 


б = Text buffer without attributes 

10 = Text buffer exists but don^t use for 
automatic update 

14 = Text buffer without attributes but 


don’t update 
06.Ұ2 ; 
DC. W 4096 ў 
DC. W 4096 ; 
DC.W 640 ; 
DC.W 400 ; 
DC.W 40 4 
DC.W 30 : 
DC.W 16 Ы 
DC.W 16 M 
DC.W 16 р 
DC.W4 ) 


String Space growth rate 
File Buffer Space 
Document Width 

Document Height 

Border Width 

Border Height 

Horiz Point Scale * 16 
Vert Point Scale * 16 
Aspect *16 


‚ Default font 


Default font size 
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; Character cell Height 
; Character cell Width 


; File reference for program 


$$ FREF, 128 
APPL 


FREF resc, ID = 128 

filetype 

local ID for icon list . 

no filename follows the application 


; File reference for document 


$$ FREF, 129 
TEXT 

1 

| 


; Bundle 


$$ BNDL, 128 
PROF 


FREF resc, ID = 129 

filetype 

local ID for icon list 

no filename follows the application 


bundle resc, ID = 128 

the epplication's signature again 
ID is again 8 by convention 

two resc types in the BNDL list: 
map one icon list: 

local ID Ø -> actual ID 128 


mep one FREF list: 
local ID Ø -> actual 1D 128 
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Basic School 


This is the anniversary of Basic Wars which began a year ago. 
This time there is a real winner! After a lot of struggle it appears 
that ZBasic™ has now come out on top. Version 4.0 is now 
available. If nothing has broken between what I’ve seen and the 
final release, ZBasic™ should be 99% free of problems (famous 
last words). The program at the end of this months column was 
written using version 3.85 beta which is supposed to be like 
version 4.0 except without the new editor. Even without the 
editor, I am extremely excited about ZBasic™ now (NO MORE 
BOMBS!!!). 

Enhancements to ZBasic™ before version 4.0 are: 

• NEW MANUAL: 206 pages dedicated to just the Macin- 
tosh, including many many examples. 

е TOOLBOX supported: documentation is now provided to 
use toolbox commands at will. 

• NEW COMMANDS such as TEHANDLE, SELECT 
CASE, GET WINDOW, HANDSHAKE, SHUTDOWN, 
FLUSHEVENTS. 

Ok, enough of that. The real reason we are here is to discover 
how to program in Basic. If you have been watching this column 
over the past several months you will see that there have been 
thingsI've wanted to do with Basic that was not supported by any. 
version of Basic. In addition, we have received many letters from 
frustrated readers trying to use Basic to do things that should have 
been easy but not supported. I'll attempt to patch the holes in the 
past columns by showing you how in the ‘new’ ZBasic. 

Michael Crichton Reads MacTutor 

One letter I received recently was from a fellow author, 
Michael Crichton. For those of you that don't know him, he was 
author of the book, “The Andromeda Strain" and has just released 
a new book, "SPHERE" (How's that for a plug for your new 
book, Michael?). Anyway, in his letter, he indicated that he 
wants “to manipulate text strings as a resource in a compiled 
ZBasic program". The basic theme of this month's column is 
"Using Resources with ZBasic". 

The idea that I will show is to use a string resource of type 
‘STR ‘ to store data that is to be used by the application the next 
time that itis run. In this case, I will store the current font and size 
in the string resource. The other half of this column finishes up 
what got started in the past several columns. If you remember, 
I attempted to read the font names from the system file and install 
them into a Font menu. With PCMacBasic it was determined that 
even though you could use the ADDRESMENU toolbox call and 
create the menu, PCMacBasic would not let you access any new 
menus. UGH! Then there was MS Basic which let you read the 
font resources through library calls (though a roundabout way), 
but would only let you have 20 items in a menu. Since many of 
you have hard disks and want more than 20 fonts, that limited 
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Basic 


Using Resources with ZBasic 4.0 


Dave Kelly 
MacTutor Editorial Board 
MacTutor Vol. 3 No. 8 


€ File Edit Font Size | 


Read MacrTutor'" |! 


Fig. 1 A Font and Size menu that really works in Basic! 


your programs to those fonts that you could fit. Even previous 
versions of ZBasic had problems, but since it works now and I 
can’t remember exactly the problem (probably a bomb!) we 
won’t discuss it. 
Font Menu That Works 

To use ADDRESMENU to load the font resource names into 
a menu I use the function GETMHANDLE (=line 39) to get a 
handle to the menu I want to add items to. In this case, I have 
already set up a ‘Font’ menu with a previous menu statement 
(=line 30). (Sorry, you’ll have to count lines yourself). The 
FontMenuHandle& variable now contains the handle to the font 
menu. FontMenuHandle& is used in the call to ADDRESMENU 
(=line 40). The resource type for the ADDRESMENU call is 
represented by СУ(“ҒОМТ”) as shown by looking on page E- 
201 of the new ZBasic manual in the ‘Alphabetical Listing of 
Toolbox Terms’. There is no more confusion on what kind of 
parameter needs to be used in a toolbox call; just look up the terms 
if you need help. OK, now the ‘Font’ menu is set up. 

Finding the application 

Next the program sets up the string resource that will be used 
to store the font and size. In my first attempt, I tried using the 
global memory location CurApRefNum found on page E-198 to 
get a RefNum to use in resource statements to indicate the 
resource file that I wanted to use (in this case, I wanted to use the 
application itself). BUT... ZBasic opens up the printer driver 
automatically for you when the application is launched and 
CurApRefNum turns out to be the reference number for the 
printer driver and not the application. The program worked fine 
under those conditions, but the string was being saved in the 
printer driver resource and not in the ZBasic application. If you 
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recall, I complained about the printer driver opening up several 
months back when we discussed ZBasic printing. This could 
have led to a real problem except that I found that the global 
memory location CurApName still contained the name of the 
application. WHEW! If notforthis, ZBasic would be branded as 
not being able to find its own application (in case somebody 
changes the name or location of the application). Lines 42-47 get 
the application name from CurApName. 

Next the application resource file is opened with OPEN- 
RESFILE and the file reference number is returned. Lines 51-57 
were added for error handling just in case something goes wrong 
although these lines will probably never have to be used. Lines 
60-67 setup the string (‘STR ”) resource. If the string resource 
handle strHnd& is zero then the resource does not exist and is 
created with ID#=1000. Otherwise the handle strHnd& will refer 
to the string stored previously (the last time the application was 
run). This string resource must now be converted to a ZBasic 
string variable and converted into font and size information 
(Lines 69-72). The function I call ReturnString$ is defined in 
lines 14-20 and reads the string referred to by the handle strHnd& 
into the string variable returned by the function. 

Menu items 

The next several lines determine which menu item matches 
the set up that has just been read in and checks the appropriate 
item. The items were searched by using the GETITEM toolbox 
call. Then in line 91 the font number which matches the font 
name is read using GETFNUM and the font and size can now be 
set with ZBasic's TEXT statement. A NOTE HERE: I tried 
CALL TEXTFONT and CALL TEXTSIZE to change the font 
and size information but these commands did not work when 
BREAK ON was being used. By removing BREAK ON every- 
thing seemed ok. This apparent bug could give somebody a few 
headaches someday. I recommend that you use the TEXT 
statement because it works better and sets the font, size, face, and 
mode in one statement. This still doesn't excuse Zedcor from 
eventually fixing this bug. 

Dialog Statement Fixed 

The remainder of the program handles the menu events. 
There are a few more comments about event processing. Several 
months back, I showed how to use ZBasic DIALOG statements 
(not used in this month's program). At that time, ZBasic did not 
quite function properly. There are a few corrections that should 
be made to the dialog example program published in the January 
1987 MacTutor. The new improved program is printed in the 
new ZBasic manual on page E-68 as Example 1 for the DIALOG 
statement. The old program will bomb with version 4.0. The 
reason is that the DIALOG ON/OFF statements must each have 
an ON DIALOG statement to tell the compiler where the DIA- 
LOG events will be handled. What counts is that it now works 


wonderfully!! IF you are having problems with implementing . 


DIALOG statements then be sure hat the DIALOG ON/OFF 
statement includes the portion of the program that you wish to 
trap dialog events and that there is a ON DIALOG statement to 
go with it. 

AS you can see, the main event loop (lines 97-102) is the only 
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part of the program that will allow events to control the program. 
During the remainder of the program, events will be held in queue 
until the program returns to the main loop. Event trapping in 
ZBasic works differently than in MSBasic because of the way it 
is compiled. I (almost) like to think of the DIALOG ON/OFF, 
MENU ON/OFF, BREAK ON/OFF and other event statements 
to be compiler directives rather than Basic commands because 
they actually instruct the compiler as to which parts of the code 
the event trapping will occur. 

SELECT CASE isa welcome improvement when it comes to 
handling menu events. The code is really easier to write (and to 
read later). 


That about wraps it up for this time. Have FUN!! 
REM ZBASIC RESOURCE EXAMPLE 


REM @MacTutor 1987 

REM By Deve Kelly 

REM IMPORTANT: COMPILE THIS PROGRAM AS 

REM AN APPLICATION BEFORE RUNNING! ! 

REM Resources аге used which need to be 

REM written to application’s own resource file 


WINDOW OFF:REM Turn off default window 

BREAK ON :REM This line mag be deleted after progrem 
debugged. 

DEFSTR LONG:DEF MOUSE=-1:COORDINATE WINDOW 


REM convert string resource to а string, given hendle. 
LONG FN ReturnStr ing$CSHnd1&) 
FByteZ=PEEK(PEEK LONG(SHnd1&)) 
Str ing$="" 
FOR i$-1 TO ҒВ8уіе% 
Str ing$=Str ing$+CHR@(PEEK(PEEK LONGCSHnd182*182) 
NEXT 1% 
END FN» String$ 


WINDOW 81,7” (50, 1002-(450,3002,4 : REM Main window. 
False=0: True=NOT(False) 

0ldFont=8:01dSize=12 

REM Setup menus 

APPLE MENU “About this application.” 

MENU 1,0,1,"File^ 

MENU 1,1,1,"Quit^ 

EDIT MENU 2 

MENU 3,0, 1, "Font^ 

MENU 4,0, 1, "Size" 

MENU 4, 1, 1, "9 Point” 

MENU 4,2, 1,710 Point” 

MENU 4,3, 1,712 Point” 

MENU 4,4, 1,714 Point” 

MENU 4,5, 1,718 Point” 

MENU 4,6, 1, "24 Point” 

SizeMenuHendle&-FN GETMHANDLE(4) 
FontMenuHandle&-FN GETMHANDLEC3) 

CALL ADDRESMENUCFontMenuHandle&, CV I C*FONT^2) 


REM Find out what this application is named.. 

CurApName-&H9 10 

СигАрМәлеф-”” 

FOR 1-1 TO PEEKCCurApName) 

i Cur ApName$=Cur ApName$+CHR§ (PEEK CCurApName * 12) 
EXT I 


REM Open application resource file 

Refnum=FN OPENRESF ILE (Cur ApName$) 

Errnum=FN RESERROR 

LONG IF Errnuno 

BEEP 

PRINT "ERROR # *;Errnum 

PRINT^Problem with Application Resource File!” 
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FOR 1-1 TO 1000:NEXT I:END 
END IF 
StrHnd&-FN GETRESOURCECCVIC“STR 42, 1000) 


REM Setting up string resource to save default font and size 
LONG IF StrHnd&=0 

Str$-"Chicago. 12" 

StrHnd&=FN NEWSTRING(Str$) 

CALL ADDRESOURCE(Strtind&, CVIC“STR “), 1000,7”) 


ELSE 
StrHnd&=FN GETSTRING( 1000) 
END IF 


REM Convert default font end size 

default$-FN ReturnStr ing$(StrHnd&) 

defaul tfont$=MID$Cdefault$, 1, INSTRC1, defau1t$, *. 5-1) 
Fsize=VALCMID$(default$, INSTRC 1,defau1t$, ^. 5*1») 


REM Check default font in Font menu 
fontcnt$-FN COUNTMITEMS(FontMenuHendle& ) 
FOR 1=1 TO fontcnts 
CALL GETITEMCFontMenuHandle&, i, item$) 
IF item$=defaultfont$ THEN 01dFont=i: i=fontcntS+! 


NEXT i 
CALL CHECKITEMCFontMenuHandle&, 01dFont, True) 


REM Check default size in Size menu 
sizecnt3=FN COUNTMITEMSCFontMenuHandle&) 
FOR ігі TO sizecnt% 
CALL GETITEMCSizeMenuHandle&, i, item$) 
sname$=MID$CSTRE(Fsize),2)+” Point’ 
E item$=sname$ THEN 01dSize=i: i=sizecntS+! 
i 
CALL CHECKITEM(SizeMenuHandle&, 01dSize, True) 


CALL GETFNUMCdefaultfont$, FnumZ) 
TEXT FnumS,Fsize, 0,0 

GOSUB "Display" 

ON MENU GOSUB ^MenuEvent^ 
FLUSHEVENTS:MENU ON 


REM Loop here until something happens 
“Loop” 


DO 

UNTIL 
MENU STOP 
END 


*MenuEvent ^ 
Menunumber-MENUCE):Menuitem-MENUC 1) 
MENU 


SELECT Menunumber 
1 

GOSUB "File" 
2 

60508 “Edit” 
3 


GOSUB’Font’ 
CASE 4 
GOSUB’Size” 
CASE 255 
IF Menuitem=1 THEN GOSUB “About” 
60508 “Display” 
CASE ELSE 
END SELECT 
RETURN 


“About” :REM About menu 
WINDOW 82,7” (75, 100)-С400, 250),-2 
TEXT 2, 14, 1,8 

N 


PRINT 
PRINT SPACE$( 11); "ZBasic" Resource Sample” 
PRINT 
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TEXT 2, 12,0,0 


PRINT SPACE$( 15); “@MacTutor, 1987 by Dave Kelly” 


PRINT 


PRINT SPACE$( 12); “ZBasic™ Version 4.0 - IT WORKS!!!!/ 
PRINT 


^u ON 
UNTIL MOUSECO? O0 
MOUSE ОРЕ 


F 
WINDOW CLOSE #2 
GOSUB “Display” 
RETURN 
“File” 
ES. UPDATERESF ILECRef Num) 


“Edit” : REM Edit menu - used for DA’s only 
RETURN 


“Font” : REM Font menu 
CALL CHECKI TEM(FontMenuHand1e&, 01dFont, False) 


CALL GETITEMCFontMenuHandle& , Menui tem, FontName$) 


CALL CHECKITEMCFontMenuHandle&k, Menui tem, True) 


CALL GETITEMCFontMenuHandle&, Menui tem, defaul tfont$) 


CALL GETFNUMCdefaultfont$, Fnunt) 

IF Menuitemo Ol1dFont GOSUB "SetResStr ing” 
OldFont-Menuitem 

GOSUB “Display” 

RETURN 


“Size” : REM Size menu 
CALL CHECKITEM(SizeMenuHand1ek, 01dSize, False) 
CALL CHECKITEM(SizeMenuHandle&,Menui tem, True) 
SELECT Menuitem 
CASE 1 
Fsize-9 
CASE 2 
Рѕіге= 10 
CASE 3 
Fsize=12 
CASE 4 
Fsize=14 
CASE 5 
Fsize=18 
CASE 6 
Fsize-24 
END SELECT 
IF Menuitem©01ldSize GOSUB "SetResStr ing” 
0ldSize-Menuitem 
GOSUB "Display" 
RETURN 


REM Set string to be saved in string resource 
“Se tResS tring” 

def aul t$=defaul tfont$+”. “+MID$CSTRE(Fsize), 2) 
CALL SETSTRING(StrHnd&, default$> 

CALL CHANGEDRESOURCE(S trHnd& ) 

RETURN 


“Display” :REM Main screen display 
TEXT Fnum%,Fsize,0,8 

CLS 

PRINT “FONT: ”;defaultfont$ 

PRINT "SIZE:^;Fsize 

PRINT 

TEXT ,,1,0 

MacTutor$="Read MacTutor™ !!^ 

REM Center MacTutor string 
Px1s$-FN STRINGWIDTH(MacTutor$) 
Windwidth$-WINDOWC6) 

CALL MOVEC CWindwidth%-Px1s%)/2,8) 
PRINT MacTutor$ 

RETURN 
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Toolbox Event Manager from ZBasic 


Let’s explore ZBasic from the perspective of the 
toolbox. At this point it should be observed that although 
ZBasic (version 4.0) works, it does not answer a few of 
our needs. Perhaps we can encourage Zedcor to add a 
few missing features which I will explain here. 

As most of you know, programming the Macintosh in 
most languages involves heavy use of the toolbox rou- 
tines. You might say that programming in Basic makes 
you soft. That’s why so many programmers move on to other 
languages like Pascal or C. It is easy to be lazy when the 
implementation of the language does most of the complex 
programming for you. Actually, once you know what to do, the 
complex stuff doesn’t seem so bad. However, because ZBasic 
provides statements which do a set of toolbox functions for you, 
your time is free to work on the organization problems of your 
program. 

DOS versus Mac OS 

In arecent discussion on the merits ( or demerits) of MS/DOS 
with a co-worker, my friend remarked that he thought that MS/ 
DOS had more flexibility than the Mac operating system because 
the programmer could manipulate files with “powerful” state- 
ments (that he had to remember long enough to type into the 
computer in the correct syntax, I might add). Of course, we (as 
Mac programmers) all know that the power of the Mac goes 
beyond “powerful” statements to copy files. The Mac user 
interface allows “the rest of us” to cut through the mush and get 
to the heart of the machine. I wonder how much time has been 
wasted by MS/DOS users as they wade through their manual to 
figure out how to do something as simple as copying a file. Their 
time could have been used more usefully. After all, computers 
are supposed to make life easier, right? 

Hard to Program? 

The only reason I mention all this is that I feel that the Mac has 
taken a lot of flak about begin hard to program. Well, some have 
found it very difficult to program, especially when they don’t 
follow standard guidelines and try to write with the “look and 
feel” of MS/DOS on the Mac! ZBasic is different. If you want 
to program with toolbox calls exclusively, you can still do it. Or, 
if using ZBasic statements (like MENU or WINDOW) would 
make iteasier, then use them. Maybe now that ZBasic is here the 
rest of the world out there might notice that it isn't so hard to 
program the Mac after all. 

Some Things Require Direct Intervention 

There are a few things that ZBasic does not yet support. А 
disk insertion event is one of them. ZBasic does mount and 
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The quick brown fox jumped over the lazy dogs back 


mple P 


Fig. 11M Sa rogram in ZBasic 

unmount volumes properly, but to sense the insertion of a disk 
requires us to create our own GETNEXTEVENT loop. The 
problem with this comes with the fact that if you use your own 
GETNEXTEVENT loop you will not be able to do any ON 
DIALOG or ON MENU etc. type event trapping. You will be 
trapping events yourself the same way that Pascal or C program- 
mers do it. ZBasic inserts a GETNEXTEVENT statement at the 
beginning of every line between the ON and OFF statements 
(such as MENU ON or DIALOG ON). If you insert your own 
GETNEXTEVENT you will lose some events to the ZBasic 
GETNEXTEVENT statements. There may be times when you 
need to have precise control over where the GETNEXTEVENT 
is placed. Fortunately, you can do this (yes, it can and may be 
done), but it requires you to abandon some of the built-in 
capability and rely on the toolbox directly; i.e., become a “real” 
Mac programmer! In some ways this is better anyway. And... 
you may still mix ZBasic statements (any that don't trap events) 
along with the toolbox statements. 

This month I have adapted the Sample program found at the 
beginning of Inside Macintosh vol 1 into a working ZBasic 
toolbox program. This program has revealed some interesting 
things about ZBasic which should be noted. 

Event Manager and ZBasic 

The Macintosh is event-driven. That is, the application 
decides what to do from moment to moment by requesting 
information from the Event Manager portion of the toolbox 
ROM through the GETNEXTEVENT statement and then re- 
sponding to each event one by one in an appropriate way. 

Most events are held in a queue called the event queue. The 
event queue normally has a capacity of 20 events. The event 
queue is a FIFO (first-in-first-out) buffer which holds events 
until they can be read from the queue. 

There are several different types of events which the Event 
Manager will keep track of. The most important of these are 
Mouse-down, Mouse-up events; 

Key-down, Key-up events including Auto-key 
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events which occur when the user holds down a 
repeating key; 

e Disk inserted events; 

Other important events include update and activate events 
which involve events which concern the Window Manager. The 
Event Manager always returns the highest-priority event avail- 
able of the requested types. 

First thing to mention is the method for setting up records of 
various kinds found in Inside Macintosh. The procedure is fairly 
painless. For example, the event record must be defined. In 
Pascal the event record is defined as: 


TYPE EventRecord = RECORD 


what: INTEGER; (event code} 
message: LONGINT; (event message) 
when: LONGINT ; (ticks since startup} 
where: Point; (nouse location) 
modifiers: INTEGER; (nodif ier flags) 

END; 


Remember that Pascal integer types are 2 bytes, and longint 
types are 4 bytes. By declaring ZBasic's static variables, the 
location of the record will be preserved where we will always 
know where to find it. Therefore we define the event record in 
ZBasic as follows: 


nyEvent$-0 ‘event code 
message&=0 “event message 
when&=9 ‘ticks since startup 
where&=8 ‘mouse location 
modif іегѕ=0 ^nodif ier flags 


The ‘what’ variable is the same location as myEvent% as 
shown by the Pascal record. The other variables of the record 
follow sequentially in memory. That is, the next variable de- 
clared is statically defined at the next memory location. The only 
thing left to do is use the GETNEXTEVENT statement to see 
what events happen. Of course it may be harder to decide what 
you want to happen when the event occurs. This is where the 
ZBasic built-in automatic statements would have been nice to 
use. When GETNEXTEVENT is called, the event record will 
then contain the desired information regarding what, when, 
where and other pertinent information. Unwanted events may be 
screened out if desired. Maybe you only want to know when a 
key is pressed and don't care about any other events. 

This quick overview will never be a substitute for your own 
experience, butI will attempt to explain some of the 'features' of 
the Sample program. 

Mixing Event Manager Calls with ZBasic 

The typical ZBasic program for the Macintosh should start 
out with the WINDOW OFF, COORDINATE WINDOW state- 
ments and if the mouse is used any place you will probably want 
to use the DEF MOUSE--1 statement. These statements turn off 
the default window, set the coordinate system to pixel coordi- 
nates and set up the mouse to read in a more Macintosh like mode. 

The charCodeMask and keyCodeMask variables are masks 
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we may use to mask the keyboard events to get the character and/ 
or key code of keys pressed. It would be helpful for you to read 
about the Toolbox Event Manager in Inside Macintosh for a 
complete overview events and how to handle them. 

The label “EventLoop” starts the main event loop. You may 
have loops within loops, even using ZBasic event statements 
within subroutines called from the main loop, but just keep in 
mind how the events will be handled. ZBasic events should 
definitely be confined to their own subroutines and turned off at 
the end of the routine. 

The SELECT-CASE statement lends itself very well to the 
toolbox implementation of event trapping. Be careful not to exit 
a CASE statement with out going through the END CASE 
statement. For example if you try to do a RETURN from within 
the CASE structure you may have unpredictable results, such as 
system bombs?? 

How to Handle Variable Screen Size 

I'm excited about the new Macintosh II and the possibility of 
larger screens and color. This will also mean that programmers 
must be aware that much more, of the expected uses of their 
program. I suppose that if you know for certain that your 
application is only going to be run on a 9" screen Mac then there 
is no problem in programming the window to open to (0,0)- 
(512,342). Remember that Macintosh II or other users with large 
screens are not going to think much of your program if it doesn't 
open to full screen size. 

How do I know how big the screen is? Well, the answer is not 
found in your ZBasic manual. The manual will help you get 
there, but not without some help from Inside Macintosh. In 
Pascal, the Quickdraw global variable, screenbits.bounds, refers 
to the rectangle of the screen of the Macintosh being used. But 
ZBasic can't access screenbits directly because it is accessed 
through internal 68000 registers relative to А5. Fortunately there 
is another way to do it. The global variable WMgrPort (at $9DE) 
points to Window Manager port. [ Note: Is there a better method 
of finding this global variable than hard coding a memory 
address which could change in future memory management 
implementations? How about calling the toolbox window man- 
ager routine GetWmgrPort? -Ed ] The Window Manager port is 
a grafPort that has the entire screen as its portRect and is used by 
the Window Manager to draw window frames. 

For those of you that don't know what a grafPort is: a grafPort 
includes a bitmap to draw in, a character font, patterns for 
drawing and erasing, and other pen characteristics. When you 
open a window, a grafPort is created for that window. You may 
set the grafPort to the current window by using the SETPORT 
call. The pointer to the grafPort of the current window can be 
found by using the statement: GET WINDOW #1, GrafPtr&, 
where GrafPtr& contains the pointer. More on this is found on 
page E167 of the ZBasic Manual (4th edition). Also found on that 
same page is a description of the grafPort record (also found on 
page 1148 of Inside Macintosh). 

Notice that the 8th byte of the record contains the boundary 
rectangle of the image (called PortRect). The boundary rectangle 
of the Window Manager Port is the entire screen of whatever 
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Macintosh the application is being run on. Therefore all that is 
necessary is to PEEK LONG (2 bytes) the WMgrPort pointer to 
see what the boundary is. Example: 


WMgrPort&-PEEK LONGC&HODE ) 
PortRecttop-PEEK WORDCWMorPort&+8) 
PortRectlef t-PEEK WORDCWMgrPor t&+ 19) 
PortRectbottom-PEEK WORD CWMgrPor t&+12) 
PortRectright=PEEK WORDCWMgrPor t&* 14) 


Now that you have the boundary you can open your window 
to an appropriate size, for example: (4,24)-(PortRectright- 
4,PortRectbottom-4) represents the rectangle the size of the 
entire screen minus the menu bar and alittle on the sides for good 
looks. In the sample the variable windowrect%(0) represents the 
rectangle for the window opened by the program. More on 
GrafPorts can be found in chapter 6 (Quickdraw) and chapter 9 
(Window Manager) of Inside Macintosh Vol. 1. 

Toolbox Call Fixes ZBasic Bug 

I found something about ZBasic type 1 windows that can be 
programmed around by opening your window with the 
NEWWINDOW toolbox function. If you use the following code 
instead of the NEWWINDOW method you will find that theright 
border of my blank window gets erased at the place where the 
scroll bars would be if I had any. Apparently, the window 
housekeeping fora type 1 window assumes or clears space for the 
scroll bars even if you don’t have any. 

WINDOW 1,"Sample Window’, Cdragleft, dragtop*20)-Cdragright-4, 

dragbottom-4), 257 
myW indowk=WINDOWC 14) 


1,7677, 7, ea a o a a ata a eae ee E ae УР И ae А tates. 
ee o o ote emn PP a eR ak ad ағады Imt Rm unum m e mnn AS. 


Зым" "ТАЛЛ es ma УС id he a a QE Um LR OM 


we eu e s e mw wu e erm ur e m n^ uu ee yu utu E tum жабыл қ балын қ Оқыр E tet даа дық 


This is a test. Thi 


s" is missing! 


This doesn't happen if I use NEWWINDOW to create the 
window. You can see this as you type in some text and look at 


eo ee ee РР 


we e www v m o e m v n m s wm y o m a a ww ww e v wu v qw o e v v a m v o a uu v" o шық s" n n v n e e a" a o o n" o i o e ш и n ns 


This is a test. This E 
NEWWINDOW function E 
works better 


I'm using ZBasic version 3.85 so hopefully this minor annoy- 
ance can be remedied by Zedcor. Fortunately, there is an 
alternative that is compatible with ZBasic statements. Remem- 
ber some of the other Basic interpreters/compilers that aren't so 
lucky. 

As you can see from this example and some of the past few 
columns of Basic School here in MacTutor we are well on our 
way to creating a full text editor in ZBasic. Why is this 
important? Because it proves Basic really can access the power 
of the Mac ROMs and support real Mac programs. Stay tuned for 
more... 
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REM Sample Demo Cadapted from Inside Macintosh) 

REM ®MacTutor 1987 

REM By Deve Kelly 

WINDOM OFF 

COORDINATE WINDOW 

DEF MOUSE-- 1 

everyevent-- 1:REM ALL events 

Ға15е=0: Тгие=МОТ Felse:donef lag-False 

REM Setup the EventRecord 

myEvent%=0:REM ‘what’ is first variable 

message&=0 

when&=9 

where&=0 

modif iers=9 

app lemark=&H 14 

whichw indow&=8 

DIM Rect%(3),windowrect%(3) 

charCodeMask&=VAL C ^&HOO0000FF ” ) 

keyCodeMask&= VAL(C"&HOOO0FF 20^) 

FLUSHEVENTS 

GOSUB “SetUpMenus” 

WMgrPort&=PEEK LONGC&HODE ) 

PortRecttop=PEEK WORD(WMgrPor t&+8) 

PortRectleft=PEEK WORD(WMgrPort&* 10) 

PortRectbottom-PEEK WORDCWMgrPor t&+ 12) 

PortRectright=PEEK WORDCWMgrPor t&+ 14) 

dragtop=Por tRecttop+24 

draglef t=Por tRect lef t+4 

dragbottom=Por tRectbottom-4 

dragr ight=PortRectright-4 

CALL SETRECT(windowrect£(0), dragleft, dregtop*20, 
dragright-4, dragbottom-4) 

myWindowk-FN NEWWINDOW(O,windowrect$(0), “Sample Window’, 1 


0,1,0,0) 
CALL SETPORT(nyWindow&) 
CALL GETPORTCGrfPtr&) 
txRect 1&-PEEK LONGCGrfPtr&* 16) 
txRect2&-PEEK LONGCGrfPtr&*20) 
CALL INSETRECTCtxRect 1&, 4,2) 
textH&-FN TENEWCtxRect 1&, txRect 1&) 


4 


*EventLoop^: REM Main Event Loop 
00 


CALL SYSTEMTASK 

CALL TEIDLECtextH&) 

CALL SETRECT(Rect$CO),PEEK WORD (GrfPtr&+16), 
PEEK WORD CGrfPtr&*18), PEEK WORD CGrfPtr&*20), 
PEEK WORD (GrfPtr&+22)) 

Cl ick=MOUSE (02 ) : xpos=MOUSEC 1): ypos=MOUSE(2) 

InRectangle=FN PTINRECT(xpos, Rect%(@)) 

IF InRectengle THEN CURSOR 1 ELSE CURSOR 

LONG IF FN GETNEXTEVENTCeveryevent, myEventS) 

SELECT myEvents 

CASE 0 :REM No Event 

CASE 1:REM mousedown 
wResult-FN FINDWINDOWM(where&, whichwindow&) 
SELECT wResult 
CASE Ø  :REM inDesk (do nothing) 

CASE 1 :ВЕМ inMenuBar 

mResult&=FN MENUSELECT Cwhere& ) 

608UB *DoCommand^ 
CASE 2 :ВЕМ inSysWindow 

CALL SYSTEMCLICK (myEvent, whichwindows) 
CASE 3 :ВЕМ inContent 

LONG IF whichwindow& © FN FRONTWINDOW 

YN SELECTWINDOW (whichwindow&) 


CALL GLOBALTOLOCAL (where&k) 
boolean=FN BITAND(modifiers,512)<>6 
CALL TECLICK (where&, boolean, textH&) 


END IF 
CASE 4  :REM inDrag 


LONG IF whichwindow& ЕМ FRONTWINDOW 
CALL SELECTWINDOW( wh ichwindow&) 
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XELSE 
ERE DRAGWINDOWCwhichwindowk, where&, dragtop) 


CASE 5 :REM inGrow 
CASE 6 :REM inGoAway 
END SELECT 
CASE 2:REM mouseup 
CASE 3,5 :REM keydown or autokey 
theChar&-FN ВІТАМ№О Стеѕѕаде& , charCodeMask& ) 
LONG IF FN BITAND(nodif iers,256209 
mResult&-FN MENUKEY(theChark) 
GOSUB “DoCommand’ 
XELSE 
CALL TEKEYCtheChar&, textH&) 
END IF 
CASE 4:REM keyup 
CASE 6:REM updateEvt 
CALL BEGINUPDATE(message’& ) 
CALL ERASERECT(txRect 1&) 
CALL TEUPDATECtxRect 1&, textH&) 
CALL ENDUPDATE (message. ) 
CASE 7:REM diskEvt 
CASE 8:REM activateEvt 
LONG IF FN BITAND(modifiers, 1202 
CALL TEACTIVATEC tex tH&) 
CALL DISABLEITEMCMhnd12&, 1) 
XELSE 
CALL TEDEACTIVATECtextH&O 
ee ENABLE I TEM(Mhnd12&, 1) 


CASE 10 :REM networkEvt 
CASE 11 :REM driverEvt 
CASE 12 :REM app lEvt 
CASE 13 :REM app2Evt 
CASE 14 :REM epps3Evt 
CASE 15 :REM epp4Evt 
CASE ELSE 
END SELECT 
END IF 
UNTIL donef lag 
END 
“Se tUpMenus” 
APPLE MENU “About Sample” 
MENU 1,0, 1, File’ 
MENU 1, 1,1, Quit/Q’ 
Mhnd11&=FN GETMHANDLEC 1) 
EDIT MENU 2 
Mhnd12&=FN GETMHANDLEC 130) 
Mhnd10&=FN GETMHANDLE (255) 
RETURN 
*DoCommand^ 
theMenu=FN HIWORD(nResult&) 
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theItem-FN LOWORD(CmResu!t&) 
SELECT theMenu 
CASE 255 
GOSUB "appleID^ 
CASE ! 
GOSUB "fileID^ 
CASE 2 


GOSUB “editID’ 
END SELECT 
CALL HILITEMENU(?) 
RETURN 


*eppleID^ 
LONG IF theItem-1 
WINDOW 5, ^,C190, 100?- (400,250), -2 
TEXT 0, 12,0,0 
PRINT 6(2,25"Semple adapted from Inside Macintosh” 
PRINT 6(10,32%)” 
PRINT 6C8, 42"Dave Kelly" 
PRINT @(6,5)*@MacTutor, 1987" 
MOUSE ON 
00 


-MOUSEC?) 
outsiderect=(MOUSE( 1) ‹0 OR MOUSEC12»300 OR MOUSE(225«0 OR 
MOUSE (2)? 150) 
UNTIL хоб AND NOT Coutsiderect) 
MOUSE OFF 
WINDOW CLOSE 5 
XELSE 
CALL GETITEMCMnnd10&, theI tem, Var$) 
mrefNun-FN OPENDESKACC(Var$) 
CALL SETPORT(myW indow& ) 
END IF 
RETURN 
*fileID^ 
donef lag-True 
RETURN 
*editID^ 
LONG IF NOT FN SYSTEMEDIT(theItem- 1) 
SELECT іле ет 
CASE 1:REM undo command 
CASE 3:REM cut command 
CALL TECUTCtextH&) 
CASE 4:REM copy command 
CALL TECOPYCtextH&) 
CASE 5:REM paste command 
CALL TEPASTEC tex tHé ) 
CASE 6:REM clear command 
CALL TEDELETECtextH&) 
END SELECT 
END IF 
RETURN 
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Basic Forum 
Draw Picts from Basic 


Steven Leach 
Chemical Engineer 
Santa Clara, CA 
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Create PICT Files for MacDraw™ using MS Basic 

This a solution to a problem that I was having when I was 
writing a rather complex figure in BASIC and wanted to save my 
very valuable work, but wouldn't or couldn't use the clipboard, 
or scrapbook. It seemed to me that the names for the BASIC 
pictures and the PICT file of the scrapbook seemed awful close 
so I thought why not bypass the scrapbook altogether? My first 
step was to get the format for the MacDraw™ files. [located this 
on Compuserve in Tech Note 27. But beware there appears to be 
an error in the wording of this document for it states “If your 
application is going to create or modify information that you 
want to make available to MacDraw, you will want to create a 
data file in the PICT format.” The tech note goes on to explain 
the first 512 byte header, of which the first 4 bytes is supposed to 
be “DRWG”, or “PICT”, and if the next two bytes are not “MD” 
then the rest of the header can be zero bytes (chr$(0)). Well Ihave 
news for you this just does not work , the MacDraw™ page comes 
out blank. 

However on examining the PICT files created by several 
programs like SuperPaint, and Cricket Draw I ascertained that 
the entire 512 byte header should be zeroed. Walah! my file is 
read properly. Now what about complex pictures that may be 
stored in your program as several picture strings. Well here we 
must concatonate them into a single picture string in order to get 
the fileto beread properly, as is done in the short sample program 
presented in Listing 1. 

This program will work with any MS Basic 2.0 or greater, but 
if you check, the line segments that make up the sine wave are 
individual objects in MacDraw'?M. This is fine for some cases but 
some of the items I wanted to appear as polygons, or grouped 
objects. The solution is available in the CLR libraries that are 
provided in MS Basic 3.0. If you wish to have a polygon in the 
PICT file, simply create one using the libraries. This adjustment 
is shown in Listing 2 for the sine wave picture that is later labeled 
as PICT2$. I also set the creator of the file to be MacDraw™ 

I'm in heaven; I can save my pictures for all posterity. Wait 
what happened to my picture it’s the same and yet different. As 
usual there are some sobering quirks that you need to know about 
before you start celebrating. These quirks show up in version 1.9, 
I have not had a chance to use the version 1.95 that is being 
released now. The quirks are: 

1) Any patterns that are used to draw lines are lost, the lines 

are solid lines in MacDraw. 

2) As you guessed there is the usual problem with the fonts 

that are presented іп MacDraw™ 

3) Polygons saved to the PICT file as polygons can never be 

ungrouped, but they have all of the nice properties that 
polygons have, they can be smoothed and reshaped. 
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Fig. 1 Draw PICT created from Basic 


4)1f you use an uneven pen , i.e. when the x and y dimensions 
of the pen are different; MacDraw will even the line out 
using the largest size. An example of this is given in 
listing 1&2 where the rectangle is framed with a pen that 
is (3,1). When you view the MacDraw picture you can 
see that the rectangle has a 3 pixel wide line on all sides. 

Ok wecan create MacDraw PICT files, is it possible to go the 
other way? Youbet. As a matter of fact it’s easy as long as we 
restrict the MacDraw picture to relatively simple things. This is 
required because the string variables that are used to store the 
pictures in BASIC are limited to 32767 characters. A BASIC 
program that is quite general is shown in listing 3. 

This opens up the possibility of drawing anything in 
MacDraw and then reading it into BASIC and using it as you 
wish, perhaps a template for a complex user interface screen, or 
Saving the picture as a resource to be used in your compiled 
program. It is possible to create dialogs with pictures in them to 
really wow those “С” programmers who consider BASIC a “toy” 
language. 

REM LISTING 1 

REM THIS PROGRAM IS USABLE IN ALL MICROSOFT BASIC’S VERSION 
2.0 OR REM GREATER 

REM try to create a macdraw PICT f ile 


REM Tech Note & 27 specifies the PICT file structure that is 
expected by MacDraw 


DIM Grey%(3) 
RESTORE PatternData 
FOR jZ = Ø TO 3 : READ Grey8(j%) : NEXT 


PatternData: 
DATA -21931, -21931, -21931,-21931 


REM define some objects that will be used for this demon- 
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stration 
REM read in the date that define the rectangle and circle 


DIM гесі&С3), aCircle%(3) 
RESTORE ObjectData 

READ rect%(@) 

READ rect&( 1) 

READ rect%(2) 

READ rect%(3) 

READ aCircle£(0) 

READ әСігс1е%С 1) 

READ aCircle$(2) 

READ aCircle%(3) 


ObjectData: 
DATA 10, 10, 110, 150, 100, 100, 200, 200 


X.Offset = 0 
'offset to be used in saving the picture in MacDrew 
Y.Offset = 0 


‘ if offsets not zero picture will have an upper 
‘ right corner at the location (X.Offset,Y.Offset) 


REM record first picture with pen on 

PICTURE ON 

CALL SHOWPEN 

CALL PENSIZECS, 1) 

CALL FRAMERECTCVARPTR(rect%(@))) 

CALL PENNORMAL 

CALL PENPATCVARPTR(Grey%(@)>) 

CALL PAINTOVALCVARPTRCaCircle$C222) 

CALL PENSIZEC3,3) 

FOR indx$ = Ø TO З : aCirclefCindx%) = aCirclefCindx%) + 
50 : NEXT 


CALL ҒКАМЕОУЛІ СУАКРТКСаСігс1е%(0222 
CALL PENNORMAL 

CALL MOVETO (10,10) 

CALL LINETO (100,200) 


PICTURE OFF 
picti$ = PICTURES 


REM now start the second picture 
PICTURE ON 
CALL MOVETOC 100, 100) 
FOR indx$ = 1 TO 20 
CALL LINECindx%, 10*SINCindx%)) 
NEXT 
PICTURE OFF 
pict2$ = PICTURES 


REM we must now group all of the separate pictures es а REM 
single picture before they cen be outputted to TRM 
the PICT file 


CALL HIDEPEN 
PICTURE ON 
PICTURE (X.Offset,Y.Offset), picti$ 
'use any valid offset you wish 
PICTURE (X.Offset,Y.Offseto, pict2$ 
offset to get relationship right 
PICTURE OFF 
Pict$ PICTURES 


File.Pict$ = FILESSC0, ^Nene for this Picture 27) ‘get the 


name of the file 
IF LENCFile.Pict$) < 5 THEN END 
‘if no file name then quit 


OPEN File.Pict$ FOR OUTPUT AS #1 
FOR indx® = 1 TO 512 
PRINT 51,CHRÉCOD; 
NEXT ‘print out the header for the PICT file 
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‘use same 


PRINT %1/Ріс%; 
CLOSE 81 

NAME File.Pict$ AS File.Pict$, "PICT^ 

‘type the file as PICT so can open from inside MacDraw™ 


REM This is listing 2 and is usable in MS BASIC 3.0 or 
greater 

REM create а macdraw PICT file 

REM Tech Note 8 27 specifies the PICT file structure that is 
expected by MacDraw 


' Print out the picture to the file 


LIBRARY “MSTools” 


DIM Grey%C(3) 
RESTORE PatternData 
FOR j% = 0 TO 3 : READ Grey¥C(j%) : NEXT 


PatternData: 
DATA -21931,-21931, -21931,-21931 


REM define some objects that will be used for this demon- 
stration 


REM read in the data that define the rectangle and circle 


DIM rect&(3), aCircle%(3) 
RESTORE ObjectData 

READ rect$C0) 

READ rect%C1) 

READ rect%(2) 

READ rect%(3) 

READ аСігс1е%(0) 

READ aCircle£C1) 

READ aCircle%(2) 

READ aCircle%(3) 


ObjectData: 
DATA 10, 10, 110, 150, 100, 100,200,208 


X.0ffset = 0 
‘offset to be used in saving the picture in MacDraw 
Y.Offset = 0 
‘ if offsets are not zero the picture will have an 
upper right corner at that location 


REM record first picture with pen on 
PICTURE ON 
CALL SHOWPEN 
CALL PENSIZEC3, 1) 
CALL FRAMERECTCVARPTR(Crect$(20))) 
CALL PENNORMAL 


CALL РЕКРАТСУАЕРТЕ(0ге,%(0222 
CALL PAINTOVALCVARPTRCaC ircle%(8))) 


CALL PENSIZEC3,3) 
FOR indx = 01703: eCircle&Cindx$) = 
eCircle&Cindx$) + 50 : NEXT 


CALL FRAMEOVALCVARPTRCaC ircle%(8))) 
CALL PENNORMAL 


CALL MOVETO (10,102 
CALL LINETO (100,200) 


PICTURE OFF 
picti$ = PICTURES 


REM now start the second picture as polygon 
PGon! = 9 
openPGon PGon! 
CALL MOVETOC 100, 100) 
FOR indx$ = 1 TO 20 
CALL LINECindxf$, 10*SINC indx%)) 
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NEXT 
CLOSEPGon 


PICTURE ON 
FremePgon PGon! 
PICTURE OFF 
pict2$ = PICTURES 


REM we must group 811 of the separate pictures as a 
picture 
REM before they can be outputted to the MacDraw™ PICT file 
CALL HIDEPEN 
PICTURE ON 
PICTURE (X.0ffset,Y.0ffset), рісі1% 
‘use any valid offset you wish 
PICTURE (X.Offset,Y.Offseto, pict2$ 
offset to get relationship right 
PICTURE OFF 
Pict$ = PICTURES 


File.Pict$ = FILES$CO, “Мале for this Picture ?") ‘get the 
name of the file 

IF LENCFile.Pict$) « 5 THEN END 
‘if no file name then quit 


single 


‘use same 


OPEN File.Pict$ FOR OUTPUT AS 81 
FOR indx$ = 1 TO 512 
‘print out the header for the PICT file 
PRINT %1,СНЮ%0); 
' note use of ; to prevent chr$C13) 
NEXT 
PRINT #1,Pict$; 


е Print out 


the picture to the file 

CLOSE 8] 

NAME File.Pict$ AS File.Pict$, "PICT^ 
'type the file аз PICT so сап open 

MacDraw™ 

Setcreate File.Pict$ , "MDRW^ 


'from inside 


' listing 3 
‘ This small routine reads MacDraw PICT FILES AND 
‘ displays the PICTURE 


File.Pict$ = FILESÉCI, “РІСТ”2) 
IF LENCFile.Pict$) < 5 THEN END 
then quit 


‘Get the FileName 
‘if no file name 


OPEN File.Pict$ FOR INPUT AS #1 
for input 
FOR indx$ = 1 TO 512 
'read the the first 512 byte header 
{юр$ = INPUT$CI,U 1) 
NEXT 
PICT$ = INPUTSKLOFC 1)-5 12, #1) 
^ read the rest of the file into a string 
CLOSE #1 
‘ close the file 


' open the file 


CLS 
' clear the screen and display the picture 
PICTURE , PICT$ rem; 
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| pa Dave Kelly 
Basic School ЕЗ MacTutor Editorial Board 
2Finder BAS ЕЗ Ontario, CA 


Reading & Writing Disk Files 


READING & WRITING "Z" FAST WAY 


Reading and writing data is often taken for granted. Yet we 
read and write data every time we turn on our computers. 
Fundamental to the Macintosh is the handling of graphics, 
sometimes in MacPaint format, and sometimes in DRAW or 
PICT format. Zedcor has some interesting commands that will 
speed up your data handling no matter which format you are 
using. 

The commands I am referring to are WRITE FILE (E-159) 
and READ FILE (E-126). Ihave used the examples in the manual 
asabase to setup my demo programs. Before I discuss this more, 
let's review the syntax: 


READ FILE [8] filenumber$, desinationAddress&, NumberofBy- 
tes& 

end 

WRITE FILE ІЗ! fiJenumber$, desinat ionAddress&, NumberofBy- 
tes& 


The key is to set up variables that you want to read or write, 
find the pointer to the variable (destinationAddress& ) and read 
or write the desired NumberofBytes&. Easy, right? I can just 
imagine some of the possibilities. How about acommunications 
program? Or afile transfer program? Orhow about writing your 
own minifinder? 

The WRITE FILE example in the ZBasic manual demon- 
strates a way that variables may be temporarily stored (quickly) 
to disk, run another application, then return to this program and 
read the variables back via READ FILE. This could always be 
done before (with other Basic commands), but not as fast. I've 
taken the WRITE FILE example and modified slightly to create 
a Mini Findertype program. Those of you who have been around 
the Macintosh for a while will remember the old days when the 
minifinder option was nota part of the Finder. Several minifinder 
type programs popped up. By replacing the regular finder with 
a smaller finder, space on the disk can be preserved. That was 
really all you could do when disks were limited to 400K. Now 
with 800K disks and hard disks, the need is not as great. Still, with 
all the things being added to the system file, if you don't have a 
hard disk your system disk is probably pretty full. My system file 
on my hard disk is over 1M byte (with all the fonts loaded of 
course). 


HOW IT WORKS 


First you must realize that this program will not work properly 
unless you compile it into a “full-blown” application. Since the 
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Fig. 1 Paint scroller program scrolls PICT images 


program will launch another application it will be impossible to 
return to ZBasic and load you basic source code to run it again. 
So... just compile as an application first. Also, this application 
must be located in the "blessed" folder (i.e. the system folder). 
The reason for this is that this application will temporarily take 
the place of the Finder (which also must remain in the system 
folder). In a sense, our ZBasic application becomes a system 
application. 

The program makes use of two global variables (available to 
all Macintosh applications) namely, CurApName ($910) and 
FinderName ($2F0). The variable FinderName contains the 
name of the Finder application (usually Finder"). CurApName 
contains the name of your application program. An application 
has no way to know if a user has changed its name. If the 
application needs to no its own name, it may refer to Cu- 
rApName. The trick that this application uses is to temporarily 
change the name of the Finder application to the current applica- 
tion name. The CurApName and FinderName variables are 
stored in Pascal format with length first with the string following. 
Be careful to observe the proper length of the strings. Cu- 
rApName is type Str31 which means it is a string with length 
(max) of 32. FinderName can only be 16 characters long because 
it is of type Str15. (A partial list of global variables is found on 
page E-198 in the ZBasic manual). 

Dummy first and last variables are set up to determine the 
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block of variables that you want to read. The variables will be 
read or write from that block of memory which is marked by the 
first and last variables. It is important to realize that ZBasic 
determines which variable is last during the compile process not 
during run time. This is the reason for the subroutine “Get Last 
Variable Pointer" at the end of the program. Notice that the last 
variable is defined at the very end of the program. If you only 
have a few variables to store you may want to position the first 
and last to include only those variables. Just remember that space 
should be reserved for reading variables back. Just for fun the 
program records the timer count as one of the variables to be 
stored. When the program is re-run after launching another 
application, it will check the timer again and display the elapsed 
time. 

An important additional comment is that you should remem- 
ber to tell the user what you have in mind when every you display 
a GetFile dialog box. IF your program displays a dialog box to 
load/save a file or as in this case to launch an application, be sure 
the the user knows why the dialog is displayed. If the dialog was 
displayed as the result of a menu that was selected then the 
purpose is self explanatory. Occasionally, I’ve seen programs 
that start up by displaying a GetFile dialog, without specifying 
that the application is looking for a paint type file (for example). 
Well, I don't keep my paint files in the same folder as the 
applications so I wouldn't know which type of file was being 
requested. My suggested solution is to display another dialog 
above or below the GetFile dialog which explains what kind of 
info is being requested. This is one way to make the program 
much more user usable. 

The ZBasic Quick “ZFinder” demo may spark some more 
ideas to help your next programming project. The listing is 
included at the end of this column. 


MORE FILE READING... 


The next program was derived from the READ FILE demo on 
page E-126 of the ZBasic manual. Actually the only part of the 
demo that is used here is the method of reading a paint file. For 
more information on reading paint files I refer you to my column 
in September 1985 (gee, that was 2 years ago). Using READ 
FILE we read 720 lines with 72 bytes per line. The 
BLOCKMOVE statement is used to move the paint picture into 
a reserved space in memory. Some of the variables used in the 
lst example on page E-126 are: 


X%(1),71 -> represents a single line (72 chars) of the paint 
picture. 

X$(719) -> 720 lines of the paint picture. 

FL&-» File length (does not include pattern header). 


The toolbox routine UNPACKBITS is used to decompress 
the paint file a line at a time. The BLOCKMOVE statement 
moves the unpacked picture for safe keeping until the entire file 
is unpacked. Be sure that this routine is not used between Event 
ON statements and Event OFF as it will slow down a lot. That 
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is because the Event statements cause the compiler to put GET- 
NEXTEVENT calls at the beginning of each basic line. This 
routine works about 10 times faster without GETNEXTEVENT 
traps. 

The are a few side effects of the Event loop which should be 
explained. For some reason the PUT statement didn't work 
properly outside of the event loop. Originally, I had put the initial 
PUT statement in the subroutine that reads the paint file. This 
caused the picture to be erase by some refreshing of the output 
window. But when placed in the loop, the refreshing recognized 
that there was a change. I can't explain why this happened. 
Perhaps, Andy or Michael Gariepy of Zedcor could explain this 
one sometime. 

Credit for the cursors and scrolling go to Lee Bass of West 
Covina, CA. (Thanks Lee). Lee'soriginal program had no menu 
and no event loop. Really, the event loop should be short as 
possible (this one is kind of long), but since Lee implemented the 
mouse functions without an event loop that's how it stayed. I 
would prefer that ON MOUSE be used to detect any mouse 
movements and remove all the appropriate statements from the 
eventloop. If you are just learning you may wantto try modifying 
the program by implementing ON MOUSE GOSUB type struc- 
ture to the program. Lee'scursors were created with ResEdit and 
converted to RMaker files to make it easier for you to type in 
these programs if you are so inclined. The window was divided 
in to thirds horizontally and thirds vertically to give 9 sections for 
the nine different cursors. During the main event loop the mouse 
is read to determine its position and the cursor is modified 
according to which of the window sections the coordinates fall. 
Pretty simple but maybe you have a better way. If you have any 
suggestions feel free to send them in. 

This program requires that you use RMaker to create the 
cursor resources. Since the current version of RMaker doesn't 
work well with HFS you should move the compiled application 
and RMaker out on to the desktop and run it from there. The 
RMaker source file can be in any folder. RMaker appends the 
cursorresources to the application file only if you have named the 
application the same as the name in the first line of the RMaker 
source file. If you can't find RMaker (distributed with ZBasic) 
or don't like it (or just plain don't understand it) you may want 
to create your cursors with ResEdit. The cursor resource ID 
numbers are : 


257 -> up arrow 

258 -» down arrow 

259 -> left arrow 

260 -» right arrow 

261 -» top/left arrow 

262 -» top/right arrow 
263 -> bottom/right arrow 
264 -> bottom/left arrow 
265 -> center 


To use ResEdit, create a new CURS resource for each ID 
number and either draw the cursor with its mask for each of the 
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ID numbers above or use the RMaker listing to type data directly 
into the resource. Open the CURS resource as a general type and 
type the hex code directly into the window. You can check your 
work by opening the resource again as a cursor type and editing 
as needed. This is a good way to make your own custom cursors 
too. I recommend using resources whenever possible with your 
compiled applications because it makes it much easier to modify 
things later if you have to change anything. The cursor editor in 
ResEdit will do what you need. 

Well, the column section is short this month, but you've got 
two programs to play with. Would you like to see a column about 
a particular subject? Just ask! Now that ZBasic is going strong 
there is such a large amount of material to discuss that it is 
difficult to know where to begin. Your preferences are welcome. 


Other related MacTutor columns: "Random Access Files" 
Sept. 1986; "Reading Paint Files" , Sept. 1985; "On Fonts & 
Cursors" , Oct. 1986; "Reading MacPaint Files", May 1987; 
"Scrolling in ZBasic" , April 1987. Some of these and others are 
also available in "Best of MacTutor, Vol. 1" book and "The 
Complete MacTutor, Vol. 2" book. 

An unrelated note: Among the numerous bugs in the MS 
Compiler which have come upon us here is another interesting 
one: 


CLS:N- 1: WHILE No 

INPUT; “Enter a number to print .. : *,N 
PRINT’ “М 

VEND :END 


This program gives a system BOMB when the binary version is used. 
With the decimal version everything works fine. The output is: 


Enter a number to print ... : 1E-3 1.000099Е-03 
Enter a number to print ... : 1E-4 .0001001 
Enter a number to print ... :1E-5 .0000101 
Enter a number to print ... :1E-6 .0000011 
Enter a number to print ... : 1E-7 .0000001 
Enter a number to print ...:1E-8 ВОМВ!!!! 


There has been no new response from Microsoft regarding the 
compiler. I still highly recommend ZBasic 4.0. Microsoft, are you 
listening?? 


REM ZBasic Quick Finder 

REM @MacTutor and Zedcor, 1987 

REM Adapted from E-159 of ZBasic Manual 
REM By Dave Kelly 


REM This program allows you to Execute other applications 
REM and return with 811 variables as they were 

REM THIS APPLICATION MUST BE IN SYSTEM FOLDER 

REM TO WORK WITH HFS | 

REM NOTE: ALL VARIABLES ARE RESTORED UPON RETURN 

REM TO THIS PROGRAM 


WINDOW OFF 

WINDOW? 1, **, С 100,30 )-С400,90), 2 
CurApName&=&9 10 

FinderName&-&2E0 

1=0 

FirstVariable$-0 

60508 "Get Last Variable pointer’ 


REM Check to see if returning from another application 
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OPEN R”, 1, "ZVARS" 
REM If returning from an application 
LONG IF LOFC1, 1) 10 
REM reload all the veriables 
READ FILE *1,VARPTR(FirstVeriable%), LestVerieble&- 
VARPTR(F irstVar iable%) 
TEXT 2, 12,1 
PRINT“Last Application: *;:PRINT Application$ 
PRINT“Elapsed Time: *;TIMER-StertTíime&;^ Seconds’ 
XELSE 
TEXT 2, 12,1 
PRINT SPC(5); “Welcome to Macintosh.” 
SysLength-PEEKCF inderName&) 
SystemF inder$- "^ 
FOR 1=1 TO SysLength 
SystemF inder$=SystemF inder$+ CHR$CPEEK(F inderName&*I2) 
T 


REM SystemFinder$ is the name of the original Startup appl. 
END IF 
PRINT^Please select an application to run.” 
StartT ime&=TIMER 


REM Moves This Applications filename to 
REM FinderName global variable 
FOR І-0 TO 15: REM filename MUST be less than 16 
POKE FinderNeme&*I,PEEKCCurApName&* I) 
NEXT 
REM *** Get name of application to execute 
Application$-F ILES$C1, “APPL”, , Volume) 
REM APPL-any executable file 
REM Last variable used as dummy for READ and WRITE 
LONG IF Application$="" 
CLOSE #1 
KILL *ZVARS" 
REM Restore Finder filename as desktop start-up 
POKE F inderName&, SysLength 
FOR 1=1 TO LENCSystenF inder$)+1 
are FinderName&*I, PEEKCVARPTR(SystemF inder$ )+1) 


XELSE 
RECORD*1,0,0:REM Reset file pointer to file begin 
REM *** Save Variables before executing Application 
. WRITE FILE *1,VARPTR(FirstVariable%), LastVariable&- 
VARPTR(FirstVar iable%) 
CLOSE*1 
REM Execute Application now... 
RUN Application$, Volumes 
END IF 
END 
“Get Last Variable pointer” 
LastVar iable&=VARPTR(LastVar iableZ) 


RETURN 


REM Paint Scroll Demo 

REM ®Mactutor 1987 

REM By Dave Kelly and Lee Bass 

REM Thanks Lee! ! 

REM Adapted from E-126 of ZBasic manual 


WINDOW OFF 

COORDINATE WINDOW 

DEF MOUSE=1 

Х&=МЕМС- 1) 

DIM X%C1),71 ХЖ7192:Х%(02-576:Х%(12-720 
Scroll Inc=20:’Increment for moving picture 
WINDOW *1,^^",(50,802-(430,310),3 

Wo tr&=WINDOWC 14) 

GOSUB “OpenFile” 


MENU 1,0,1,*File” 
MENU 1, 1, 1, "0pen../0^ 
MENU 1,2, 1, "Quit /Q" 
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ON MENU GOSUB "MenuEvent^:MENU ON:MOUSE ON 
*Main Program Loop^ 
00 


IF New=1 THEN PUT (-ХСһепде,-ҮСһепде),Х%(0), PSET:New=0 
MouseEvent=MQUSE (9): Hor izpos=MOQUSEC 1): Ver tpos-MOUSEC2) 
LONG IF Horizpos»9 AND Horizpos<389 AND Уегіров>0 AND 
Ver tpos<239' in our window 
LONG IF Уегіров» 153:REM bottom section 
IF Horizpos«127 THEN CursorNumber-264 
IF Horizpos>=127 AND Hor izpos<=253 THEN 
CursorNumber=258 
IF Ногі2ро5» 253 THEN CursorNumber=263 
END IF 
LONG IF Vertpos»-77 AND Vertpos<=153 
REM middle section 
IF Horizpos«127 THEN CursorNumber=259 
IF Ногігроѕ› = 127 AND Ногі2роѕ‹=253 THEN 
CursorNumber=265 
IF Horizpos»253 THEN CursorNumber=260 


END IF 
LONG IF Vertpos<77:REM top section 
IF Horizpos«127 THEN CursorNumber=26 1 
IF Ногі2роѕ› = 127 AND Horizpos<=253 THEN 
CursorNumber=257 
IF Horizpos)253 THEN CursorNumber=262 
END IF 
LONG IF MouseEvent«? 
REM cursor down change xx,yy to move picture 
IF CursorNumber=259 THEN XChange=XChange-Scrol1 Inc 
IF CursorNumber=268 THEN XChange=XChangetScrol 1 Inc 
IF CursorNumber=257 THEN YChange=YChange-Scrol1 Inc 
IF CursorNumber-258 THEN YChange=YChange+Scrol 1 Inc 
IF CursorNumber=261 THEN XChange=XChange- 
ScrollInc:YChange-YChange-Scro11 Inc 
IF CursorNumber=262 THEN 
XChange=XChangetScro1 1 Inc: YChange=YChange-Scrol 1lInc 
IF CursorNumber=263 THEN 
XChange=XChange+Scro11 Inc: YChange=YChange+Scrol1Inc 
IF CursorNumber=264 THEN XChange=XChange- 
ScrollInc:YChange = YChange*ScrollInc 
IF YChange<@ THEN YChange=0 
IF XChange«0 THEN ХСһагде=0 
IF YChange»720-230 THEN ҮСһапде=720-230 
IF XChange»576-380 THEN XChange-576-380 
PUT (-XChange, -YChange2,X$(0), PSET 
END IF 
MyCursor=CursorNumber : 
CURSOR MyCursor 


ELSE 
CURSOR 9:CursorNumber=0:REM Not in our window 
END IF 
UNTIL Finished=1 
MENU OFF :MOUSE OFF 
END 


^MenuEvent^ 

Menunumber-MENUC£) 

Menui tem=MENUC 1) 

IF Menuitem=1 THEN GOSUB “OpenFile” 
IF Menuitem=2 THEN END 

MENU 

RETURN 


^OpenF ile” 

CALL HIDEWINDOWCWptr&) 
WINDOW*2, "^ С 100,30 )-С400 552,2 

TEXT 2,12,1 

LOCATE 0,0 

CLS LINE 

PRINT SPC(5);*Please Select a Paint File to View’; 
“Load PaintPic"^ 

F$=FILES$( 1, "PNTG^, "PNTG^, VS) 

IF F$-"" THEN CALL SHOWWINDOWCWptr&):RETURN 
LOCATE 0,0 
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CLS LINE 
PRINT “Now Loading *;F$; 
REM Read in the Paint File 
OPENI”, 1,F$, 1,V8 : S&LOFC1):REM Set length of Paint File 
A&-VARPTRCA$2: Y&SVARPTRCX$CO2) :X&2A& : №256 
FL&-S&-512:CURSOR 4:RECORD 81,512 
FOR I = 1 TO 720:REM Lines in the Paint Picture 
LONG IF N> 180 
BLOCKMOVE X&,A&,256-N:X&-A& 
IF P FL& THEN NX=FL& ELSE NX=N 
READ FILE *1,A&*256-N,NX:FL&-FL&-NX 


END IF 
CALL UNPACKBITS(X&, Y& , 725 : NX&-A& 
EXT 


N 

CLOSE #1 
XChenge- : YChangez : New= 1 
WINDOW CLOSE 2 

CALL SHOWWINDOWCWptr&) 
WINDOW 1 

RETURN 


;RMaker File for Paint Scroll Program 


IPaint Scroll 
Type CURS=GNRL 


,251 
Н 
0080 0140 0220 0410 0808 1004 2002 ТЕЗЕ 0220 0220 0220 0220 
0220 0220 0220 Ø3EØ 0080 O1CO 03Е0 07Ғ0 OFFS IFFC ЗҒҒЕ ТЕРЕ 
0ЗЕ0 03Е0 03Е0 03Е0 03Е0 03Е0 03Е0 030 0000 0008 

258 
03Е0 0220 0220 0220 0220 0220 0220 0220 ТЕЗЕ 2002 1004 0808 
0410 0220 0140 0080 03-0 03Е0 03Е0 03-0 03Е0 03Е0 03Е0 03Е0 
ТЕРЕ 3FFE 1FFC ØFF8 07-0 03Е0 O1CO 0080 000Ғ 0008 

259 

0100 0300 0500 0900 1100 21FF 4001 8001 4001 21ЕҒ 1100 0900 
0500 0300 0100 0000 0100 0300 0700 0Ғ00 1-00 3FFF ТЕРЕ FFFF 
TFFF 3FFF 1Ғ00 0-00 0700 0300 0100 0000 0007 0000 

,260 
0080 00С0 0040 0000 0088 FF84 8002 8001 8002 FF84 0088 0090 
ODAO 00С0 0080 0000 0080 BOCA GEO 00-0 GOOFS FFFC FFFE FFFF 
FFFE FFFC 00Ғ8 00-0 00-0 00С0 0080 0000 0007 000Ғ 

‚261 
FFCO 8080 8100 8200 8100 8080 9040 А820 C410 8220 0140 0080 
0000 0000 0000 0000 FFCO ЕҒ80 ҒҒ00 ҒЕ00 FFOO FF8Ø FFCO ЕҒЕ0 
C7FO 83Е0 0100 0080 0000 0000 0000 0000 0000 0000 

,262 
@ТЕЕ 0202 0102 0082 0102 0202 0412 082А 1046 0882 0500 0200 
0000 0000 0000 0000 OTFE 03ҒЕ ØIFE 00ҒЕ ØIFE 0ЗҒЕ O7FE OFEE 
ІҒС6 0Ғ82 0700 0200 0000 0000 0000 0000 0000 000Е 

,263 
0000 0000 0000 0000 0200 0500 0882 1046 082А 0412 0202 0102 
0082 0102 0202 O7FE 0000 0000 0000 0000 0200 0700 0Ғ82 1ЕС6 
FEE O7FE 03FE 0ІҒЕ 00ҒЕ 0ІҒЕ 0ЗҒЕ 07ҒЕ 000Ғ 000Ғ 

‚264 
0000 0000 0000 0000 0080 0140 8220 C410 A820 9040 8080 8100 
8200 8100 8080 FFCO 0000 0000 0000 0000 0080 01С0 83Е0 CTFO 
EFE® FFCO FF8Ø FFØØ ҒЕ00 ҒҒ00 FF80 FFCO 000Ғ 0000 

,265 
0000 0080 010 03Е0 0080 0080 1004 3086 7DDF 3086 1004 0080 
0080 03Е0 01С0 0080 0000 0000 0000 0000 0000 0000 0000 0000 
0000 0000 0000 0000 0000 0000 0000 0000 0008 0008 


Programmer's Forum 
MacDraw PICT Files from Basic 


Why "Draw" a 'PICT' File? 

This article should really have been titled “ "PICT'ing in 
ZBasic™ **, but that didn’t sound quite as clear. The ‘PICT’ file 
format is rapidly becoming the standard for transferring High 
Quality graphics between programs, and not just graphics pro- 
grams. To name just a few, MacDraw™ , MacDraft'^ , Cricket 
Draw™, and SuperPaint™ all will both read and write ‘PICT’ 
files. However, layout programs like PageMaker™ will also 
read ‘PICT’ files in directly with its “Place” command. In 
addition to all of the above a word processor like Word™ 3.0 will 
pass ‘PICT’ information back and forth through the clipboard 
and retain the individuality of each *PICT' element. Why all of 
this compatibility? The answer to that one is simply called the 
“LaserWriter™ "! 

The LaserWriter with its PostScript™ language treats all 
*PICT' elements as separate objects, not bit maps, and prints (or 
better yet, draws") them vectorially. That's why a diagonal line 
has nice sharp edges, and not the “jaggies” that go with the 
individual pixels of a bit map. This even holds true for text! As 
the quest for higher and higher quality proliferates, the *PICT' 
format will become even more prevalent. The ‘PICT’ format is 
also inherently faster than most because it is the format that 
*QuickDraw' in the ROM is using to begin with! 

All of the graphics programs mentioned previously also have 
their own proprietary file format, including MacDraw. Getting 
into those formats is not the purpose of this article. It is “ 
‘PICT’ ing “ that we'll be covering in detail. And, as you will see, 
"draw"ing a ‘PICT’ file in ZBasic is even easier than “paint” ing 
a ‘PNTG’ file in ZBasic as I covered in a previous article. 


What's in the ‘PICT’ure? 

First of all, there are several good references on the ‘PICT’ 
file format and ‘QuickDraw’ ing a picture, so I’ll give them to you 
now. 

MacDraw' 5 PICT File Format and Comments, Macintosh 
Technical Note #27, by Ginger Jernigan, Aug. 20, 1986. 


QuickDraw' s Internal Picture Definition, Macintosh Techni- 
cal Note #21, by Ginger Jernigan, June 20, 1986. 


Optimizing for the LaserWriter—Picture Comments, Macin- 
tosh Technical Notes #91, by Ginger Jernigan, Mar. 2, 1987. 


Inside Macintosh™ Volume I, chapter 6, QuickDraw, in 
particular Pictures and Polygons starting on p 158. 

As Inside Mac says on page 158, “A picture in QuickDraw 
is a transcript of calls to routines that draw something—any- 
thing—in a bit image.”. Whoa!!! What happened to all this 
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Z2Basic™ 
elements, objects, and vector stuff this idiot was just talking 
about? Well, the bit image they’re talking about on page 158 is 
the screen. The things that get stored in the files and also sent to 
the LaserWriter are those calls friends, not a bit image! 

Since pictures are all of varying size, i.e., length, as we could 
have guessed a Picture is really just a variable length record. The 
record always starts with the following two fixed-length fields: 


picSize: INTEGER; (size of record in bytes} 
picFrame: Rect; {picture frame} 


Immediately following the two fixed-length fields are the 
"QuickDraw ' calls to generate the picture. Itis important to point 
out that the size (picSize) includes the first two fixed-length 
fields themselves. If we were to write out this picture record to 
a file we’d have what we need, right? Wrong! All of the 
programs mentioned previously would spit-up something ter- 
rible. So, what's missing? Well, it’s a header of some kind . . 
. that's what makes a picture record into a ‘PICT’ file. So let's 
get into that now. 


The MacDraw 'PICT' file format 

Referring you to tech note 421, MacDraw gives you the 
option to use two file formats. They are DRWG and PICT. The 
DRWG format is the internal one that only MacDraw under- 
stands. The PICT format is the one we'll look at in MacDraw. 
Rather than just drone on and on, it's time for an example. I went 
into MacDraw, itself, drew a simple five-sided ‘closed’ polygon, 
saveditasa ‘PICT’ file and then went into Fedit+™ to take a look 
at it with tech note #27 in hand. Figure 1 shows the polygon as 
you normally see it in MacDraw. 

As we can see, there's not much to it. Just an ordinary 
polygon. The total file size, as stored by MacDraw, is just 570 
bytes. That's good, since the actual ‘PICT’ ure part of it is only 
58 bytes long. À quick mental calculation tells us the header is 
our old friend, 512-bytes, long! Same length as the 'Paint' file 
headers were. Now let's view what you find in Fedit+ and take 


Fig. 1 A draw figure created from Basic! 
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a close look at the header. 

Figure 2 is the “ Fedit+ "ed look at both sectors of the 
MacDraw 'PICT' file called “Polygon”. The breaks in the sector 
viewsare where they become all zero from then on. The numbers 
in the left halves are the hex representation of the code and to the 
right is the ASCII representation. Here's what we find in the 
header (refer to tech note 4427): 


MacDraw PICT File Header 
4452 5747 fType ‘DRWG’ in ASCII for 
MacDraw 1.7 & 1.9 
4D44 hdrID ‘MD’ in ASCII 
0006 version file format version 
0003 to prRec 120 byte print record 
0000 (ends with position 000079) 


0000 0000 xOrigin 
0000 0000 yOrigin 


drawing origin 
drawing origin 


0048 0000 xScale screen res (272 dots/inch) 
0048 0000 yScale screen res (272 dots/inch) 
0000 to atrState state of drwg attributes 
0000 (ends with position 0000CD) 
0001 ICnt no. of top-level objects 
0001 ITot total no. of all objects 
0000 0066 1512 total size of list 
000A 0000 top box of all objects (= 10) 
0055 0000 left box of all objects (2 85) 
0046 0000 bottom box of all objects (= 70) 
00E1 0000 right box of all objects (2225) 
0007 to filler 282 unused bytes 
0000 (ends with position 0001FF) 


Creating this header for each different file would be quite time 
consuming and also subject to error. Fortunately we're in luck! 
Tech note #27 says “If MacDraw opens a PICT file and finds that 
it has a different hdrID than MacDraw expects, or that the first 
block is zeroed, it ignores the header and uses its own default 
document settings.". So all we will have to do to create a 
"MacDraw" ‘PICT’ file in ZBasic is to start it out with 512 bytes 
of zero (0)! The second part of Figure 2 is the data for the actual 
QuickDraw 'PICT ure of the polygon. Let's get into that now. 


Pic comments are Helpful 

MacDraw makes extensive use of picture comments [CALL 
РІССОММЕМТ(...) in ZBasic] to gain more functions than 
are available with the standard QuickDraw calls. They are also 
used to guide the LaserWriter in "drawing" a complex set of 
figures and text. А good example is using piccomments to tie 
arrowheads and lines together in order to make the combination 
a single entity, the arrowhead-line. There are two types of 
piccomments available, the so-called ‘shortComment’ and its 
companion the ‘longComment’. The long one allows you to 
specify a variable-length data record to be executed, while the 
*shortComment' has simply one operation, like “picPlyClo”, 
which means we're drawing a "closed" polygon. The only ones 
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we'll be needing here are the short comments. They are charac- 
terized by a one (1) byte ‘opcode’, which is “А0”, followed by a 
two (2) byte 'kind' which describes the action desired. 

The first item in the QuickDraw picture is always 2 bytes of 
record size, which includes the 2 bytes themselves. Then comes 
the picture frame, of type *Rectangle', which means 8 bytes (4 
wordsor integers) of rectangle description. This is followed with 
the picture definition. What we do now is look at the first byte, 
the ‘opcode’ (operation code), which tells us what is going to be 
described and then the descriptions will follow. Then welook for 
the next ‘opcode’ and the process keeps repeating until the 
picture is finished. Now ме сап take a look at that *PICT'ure data 
in the second half of Figure 2: 

Quickdraw Picture Format 


003A picSize size of entire picture, in bytes 
( 58 decimal, in this case) 
0000 picTop loc of top of entire picture 
( Odecimal, in this case) 
0000 picLeft loc of left of entire picture 
( Odecimal, in this case) 
020200 picBottom loc of bottom of entire picture 
(720 decimal, in this case) 
0240 picRight loc of right of entire picture 
(576 decimal, in this case) 
11 opcode for 'picVersion'(1 byte ) 
01 version number for this picture 
АО opcode for ‘shortComment’(2 bytes) 
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0082 


00A0 


00A5 


00A1 


0083 


418 


A0 


АО 


АО 


АО 


kind for ‘picDwgBegin’ 
(begin a MacDraw pict) 


opcode for ‘shortComment’(2 bytes) 
kind for ‘PolyBegin’ 
(begin a special polygon) 


opcode for ‘shortComment’(2 bytes) 
kind for ‘picPlyClo’ 
(the poly’n is to be closed) 


opcode for ‘clipRgn’(10 bytes, or more) 
size of entire region(10 bytes) 

top of ‘clipping’ топ ( Odec) 

left of ‘clipping’ rgn ( Odec) 
bottom of ‘clipping’ rgn (720 dec) 
right of ‘clipping’ rgn (576 dec) 


opcode for ‘short line’ (st.v,st.h,dh,dv) 
vert start pt for line (10 dec) 

horiz start pt for line(85 dec) 

dh horz line length ( 0 dec) 

dv vert line length (35 dec) 


opcode for ‘short line from’(dh,dv) 
dh horiz line length(99 dec) 
dv vertline length (25 dec) 


opcode for ‘short line from’(dh,dv) 
dh horiz line length(41 dec) 
dv vertline length (196-256=-60 *) 


opcode for ‘short line from’(dh,dv) 
dh horiz line length(166-256=-90 *) 
dv vertline length (25 dec) 


opcode for ‘short line from'(dh,dv) 
dh horiz line length(206-256=-50 *) 
dv vertline length (231-256=-25 *) 


opcode for ‘shortComment’(2 bytes) 
kind for ‘PolyEnd’ 
(end a special polygon) 


opcode for ‘shortComment’ 
(2 bytes to follow) 

kind for ‘picDwgEnd’ 

(end a MacDraw pict) 


opcode for ‘EndofPicture’ 
(nothing to follow) 


dh & dv аге both (-128 . . . +127), so if 
number is greater than +127 decimal, 
subtract 256 from it to get true neg. no's. 


Now let's take a break from all of this and get into some 
programming. 


The “MacDraw/ZBasic” Polygon Program 

The first ZBasic program at the end of this article is called 
‘“MacDrawPoly.BAS”. It is the shortest and simplest of the 
three, and was written to try a couple of different approaches to 
creating the same figure. We begin by defining the ‘opcodes’ for 
the ‘short’ piccomments we’ ll be needing, and then we define the 
picture rectangle and CALL SETRECT(... ) to initialize it. 
After this, we ‘open’ the picture and get a ‘handle’ to it 
(PicHand &); and then ‘begin’ the picture with a piccomment. I 
should point out here that the *picDwgBeg' and its converse 
'picDwgEnd' are really not necessary, but they do make the 
QuickDraw description of the picture much more efficient. 

The first file created uses piccomments to tell it a ‘polygon’ 
is coming, that the polygon is of the *closed' type, and that the 
polygon description is completed. The second file use the more 
standard QuickDraw calls to open, close, frame, and ‘kill’ the 
polygon. Now we open a file and give it a type of ‘PICT’ and 
creator of MDRW' (for MacDraw). As discussed previously, 
the first thing wedo is write-outa 512 byte header of zeroes. Then 
we get the ‘pointer’ to the picture data from the ‘handle’ we got 
at the beginning of the program. 

As you can see from the coding, PicLength 90 -PEEK 
WORD(PicPtr& +0), the length of the entire picture record is 
contained in the first 2 bytes (one word or integer) of the record 
itself. We need this to know how much data to write-out to the 
files. The ‘monkeying’ around you see to get the number of 
words (integers) from this length-of-record is merely to insure 
we'llinclude the ‘FF’ (EndofPicture) at the end of the record. I'll 
point out that with this method, sometimes you'll get an extra 
byte after the ‘FF’, before the file is actually closed (50-50 
chance). This won't hurt anything, because “MacDraw”, and all 
the rest, know that *FF' means it's all done drawing your picture! 
Figure 3 compares the ‘polygons’ as done by “MacDraw” itself, 
and as done by the ZBasic program. 


Compare the Actual Polygon File Data 

As we can see, all three polygons in Figure 3 sure look the 
same. But the proof of the pudding is to use Fedit+ again and take 
a look at the actual data. Figure 4 does this for 
"MacDraw.poly1", the first of our ZBasic files. 

Well, the first thing we notice is the 512 byte header of zeroes. 
And since “MacDraw” read it in, we know that part of the 
approach works. In comparing Figure 2 to Figure 4, we find that 
our ZBasic polygon’s ‘PICT’ data is also 58 bytes long - so far 
so good. As a matter of fact, the match is perfect except for the 
"bottom" and “right” of the ‘clip’ rectangle. These numbers are 
$0117(279 dec) and $01E7(487 dec) which happens to be the 
‘vis’ and also the ‘clip’ regions of ZBasic's default window! We 
could change the clipping region in our program to get them to 
match perfectly - but as we will see later, the only thing affected 
is what is visible on the screen when the picture is being 
generated. “MacDraw” and all the rest ignore this when they read 
in a "default-header" file and reset the ‘clip’ region as necessary. 
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Fig. 3 Comparison of the Polygons 
As a matter of fact, it changes constantly with how much 
reduction or expansion you are using at the time. The ‘PICT’ data 
for “MacDraw.poly2” was 65 bytes long and was constructed 
slightly differently. Figure 5 shows us those differences. 

The first thing we notice is that the ‘PolyBegin’, ‘PolyEnd’, 
and “рісРІуСіо” piccomments are missing, just as we coded the 
program. However there is a new ‘opcode’ at position 00021A; 
it is did which i is the opcode for ‘framePoly’. Our ZBasic 
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Fig. 4 ZBasic's 'PICT' Polygon File 
CALL FRAMEPOLY(...) produced this for us. This opcode 
is followed by ‘polySize’, ‘polyBBox’, and ‘polyPoints’ which 
are thesize of the polygon record, the bounding box, or rectangle, 
and the array of points, respectively. The method used in “ро1у1” 
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is more efficient than that used in *poly2", but for just a few 
points per polygon the payoff is not that great. Now let's get on 
to something with a little more visual appeal. 


Fill and Pen Patterns 

The second program at the end of this article, 
*MacDrawPat.BAS", will look like Figure 6 when you run it 
“interactively” in ZBasic. Referring to the listing you'll see a 
CALL SHOWPEN, which allows us to see what is going on 
while running. As mentioned in Inside Mac and the ZBasic 
manual, when we ‘open’ a ‘PICT’ ure QuickDraw makes the pen 
‘invisible’. Conversely, when we ‘close’ it, the pen gets turned 
back on. So if you want to watch, do a ‘showpen’ after opening 
the picture. Just be sure to ‘hidepen’ before you hit the 'closepic- 
ture’. 

This program gets us into patterns in QuickDraw. A pattern 
is Simply an 8 by 8 array of pixels, or data, which can be used for 
‘filling’, ‘painting’, and for ‘drawing’ by the pen. If you 
remember back when we did ‘Paint’ ing in RET we simply did 
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Fig. 5 ZBasic Version of а ‘Conventional’ Polygon 
PEN ,,,,32 and got the thirty-secondth pen pattern to use. Well 
wecan do the same thing with our *MacDraw" ‘PICT’ files. But, 
BE CAREFUL! MacDraw does NOT use the same patterns as 
the ‘Paint’ programs. It has its own patterns, while the ‘Paint’ 
programs use a set that resides in the System File. If you use a 
pattern that MacDraw does not have it will do one of three things: 


(1) default to black 
(2) default to white 
(3) spit-up all over itself 


So, we will have to get the exactly correct patterns to use. 
There are three ways to do this that I know of. First, there is a [Not 
in ROM] procedure on p 473 of Inside Mac, Vol. I, called 
"GetIndPattern' which would do it. But that procedure is not yet 
implemented in ZBasic. Second, by using ZBasic’s FN 
GETRESOURCE(...) and a little manipulation you could 
probably get the patterns. The third way is to look at the patterns, 
convert them to hex-strings, and use CALL STUFFHEX(...) 
to put them into a real pattern record. The third way is shown 
pictorially in Figure 7. First fire-up “ResEdit”, open up 
MacDraw, and find the resource ‘PAT#’. That's where the 36 
“ІШ” patterns reside. The first one is ‘None’, the second is 
‘white’, the third is ‘black’, etc. Watch that first one (None)! I 
haven't found a pattern for ‘None’ yet, so I just don't do a ‘fill’ 
if the desired pattern is ‘None’. 
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Fig. 6 ZBasic Run of "MacDrawPat.BAS" 


In order to save you the work of converting 36 patterns, they 
are all listed as ‘DATA’ statements at the end of the program. 
There are a couple of other points of interest in 
‘“MacDrawPat.BAS”. First is the sequence of the graphics 
calls. Referring to the listing you will notice that they appear in 
the following order: 


(1) draw the single-weight line 

(2) draw the ‘brick’ filled rectangle 

(3) draw the ‘diamond’ filled oval 

(4) draw the double-weight line 

(5) draw the ‘inverted-V’ filled round-rectangle 


Now looking back at Figure 6, you see that's how they are 
stacked on the screen. This is the same effect that the “Bring to 
Front" and “Send to Back" commands under the “Arrange” menu 
іп “MacDraw” will produce. You can use this to your advantage. 


‘Fil? and ‘Paint’ are NOT the Same 
The second item of interest, is that ‘filling’ and ‘painting’ are 
not the same action in QuickDraw. If you CALL FILLRECT( 
...)andthenfollow it with CALL FRAMERECT(...) you get 
a 'filled' rectangle that has the pattern and the frame 


Fig.7 'FillPattern' Conversion 
PatList ID = 100 
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“GROUPED” as MacDraw does with its ‘Fill’ menu. The top 
half of the file “MacDraw.demo” is generated this way. How- 
ever, if you CALL PAINTRECT(...)and then follow it with 
CALL FRAMERECT(...) you get a ‘painted’ rectangle that 
is"NOT GROUPED”. Inother words, the ‘paint’ can “spill” out 
of the frame. I took the file *MacDraw.demo" into MacDraw to 
demonstrate this, as shown in Figure 8. 

As you can see, the bottom three figures have their ‘paint’ 
selected and then dragged out of the frames. You can get this 
same effect in "MacDraw", itself, by drawing your shape, ‘fill- 
ing’ it with your selected pattern, and then changing its frame line 
to 0-weight (the ‘dashed’ line under the ‘Lines’ menu). The only 
reason to do it this way in our program is that ‘paint’ing avoids 
the ‘stuffhex’ call to set up the pattern and get a pointer to it. 


The “MacDrawFiles.BAS” Program 
The last program of the three is the largest and incorporates 
all of the features of "MacDraw" itself. It won't let you work 
interactively, like ‘selecting’ lines and moving them around. I'll 
let that to MacDraw and the others. But it will give you the tools 
to create a MacDraw compatible file inside of your ZBasic 
program and get the full benefit of: 


(1) any selected font family 

(2) all 8 “MacDraw” font sizes 

(3) all 6 “MacDraw” font styles & combinations 
(4) all 36 “MacDraw” fill/pen patterns 

(5) all 5 “MacDraw” line weights 

(6) all 3 “MacDraw” arrowhead lines 

(7) all 9 “MacDraw” tools along the ‘left pallete’, i.e.,: 
text 

orthogonal lines 

. diagonal lines 

rectangles 

. rounded-corner rectangles 

ovals 

arcs 

freehand 

polygons 


a ee р 


Figure 9 shows two different parts of the “MacDraw.text” 


dec hex $8080413E080814E3 
128 = $80 ———À 
168 = i41 ——— —- 
8 = $08 
8 = $08 
20 = $14 
227 = ЧЕЗ 
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file. The upper half has several different fonts, all in 12 pt Bold. 
Italso contains the 6 basic font styles and a combination of Bold- 
through-Shadow. 

The lower half uses Helvetica, in Bold, to illustrate all 8 
"MacDraw" font sizes. Although you can invoke any font size 
in your ZBasic program, MacDraw only allows these eight sizes. 
If you give it a size it doesn't have, say 16 pt, it will "default" to 
12pt. The moral of the story is ...if youare going to bring your 
iain. into MacDraw, itself, use these sizes аг even if you 


Fig. : 8 Effects of 'Palnting' 


‘fudged’ it (“Tiny 9" is an example). 

The upper left portion of Figure 10 shows most of the 36 ‘fill’ 
patterns and the upper right shows a portion of the 36 ‘pen’ 
patterns. 'Scrolling' around in MacDraw will give you a better 
look atall of them. The center portion of the upper half of Figure 
10 contains the different line weights and the start of the ‘arrow- 
head’ lines. Some more of these ‘arrowhead’ lines are shown 
down the center of the lower half of the figure. The geometric 
shapes are along the left and right sides of the lower half. 

Having mentioned 'scrolling' you should also be aware that 
if you extend your ‘work of art’ past the boundaries you set up for 
your 'picRect' the info is still there. Just go down to the bottom 
of the "Layout" menu in MacDraw to the “Drawing Size" item 
and select a few more pages to look at. You'll then be able to 
scroll around and see the ‘missing’ portions. 


Items of Special Interest 

If you look at the listing of *MacDrawFiles.B AS" there are 
several things of special interest you should note. First of all, as 
mentioned earlier, don't even bother to call ‘fillrect’, ‘filloval’, 
etc., if you want *None' for the fill. Even though it is in the fill 
data, it's just there for completeness of the data set. Second, the 
0 pen size does produce ‘invisible’ lines, but you'll never find 
them. QuickDraw does not bother to save 'invisible' lines. You 
can verify this by going directly into MacDraw, drawing a line, 
making it invisible, and saving the drawing in the ‘PICT’ format. 
Quit out of it, load the drawing, and “Select All” under the “Edit” 
menu. Nothing. Note, the MacDraw proprietary format, 
however, will save those invisible lines! 
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The third thing to take a look at is the ovalWidth and 
ovalHeight for the rounded-corner rectangles. They are both 
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shown as 20 pixels in size. I've tried several different size and 
aspect-ratio rounded-corner rectangles in MacDraw, itself, and 
they always come back 20-by-20 if you leave it's default settings 
alone. You сап go under the ‘Edit’ menu and change the corners 
to any one of 6 different settings. Our fourth item of interest is 
the so-called freehand tool. MacDraw uses the ‘polygon’ to 
describe freehand drawing . . . but not exactly. It really is a 
polygon, but I don't know what algorithm MacDraw uses to 
decide when to add a new point to the polygon. When you ‘draw’ 
freehand in your programs, you'll probably use a lot more points 
than MacDraw ever would. 

The last item is arrowheads! These were the toughest of all 
to nail down. Finally, I created a special subroutine called, 
naturally, "ArrowHeads". Just feed it the x & y coordinates of 
both end points of the line (xahl1%, yahl1%, xahl2%, & yahl2%) 
and the type of arrowhead desired (ArrwPt%=1 for end-pt 1,2 for 
2, & 3forboth) and it will figure out the angles and adjust the line 
length for the proper match with the arrowhead(s). Study the 
subroutine coding (it's heavily commented) and it will become 
clear what it has to do. 


ZBasic configuration 
Since ZBasic can be "configured" to just about any range of 
variables imagined, Гуе elected to include the configuration that 
was used forrunning the programs in Figure 11. All three will run 
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Fig. 10 'graphics' Output of "MacDrawFiles.BAS" 
with version 3.03 or higher. 


Ihe MacDrawPoly Program 
REM 
REM (MacDrawPoly.BAS) 
REM 
REM CREATES А ‘MACDRAWCPICT)’ CLOSED-POLYGON 
REM 
WINDOW OFF 
COORDINATE WINDOW 
REM 
REM DEFINE ‘SHORT’ PICCOMMENTS 
REM 
NIL&-9 
noDate$-0 
picDwgBeg%= 130 
picDwgEnd%= 131 
PolyBegin$s 160 
PolyEnd$s 161 
picP lyC10%= 165 
REM 
REM DEFINE PICTURE RECTANGLE CA FULL-SIZE ‘DRAW’ PAGE) 
REM 
picRect=@. 
рісТор%-0 
picLef {%=0 
picBot tom%=/20 
picRight£2576 
REM 
REM ‘INITIALIZE’ PICTURE 
REM 
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CALL 
SETRECTCpicRect,picLeft$,picTopS$,picRightZ,picBottomt) 
REM 
REM CREATE THE ‘MACDRAW’ POLYGONS 


REM 
FOR File%=1 TO 2 
PicHand&=FN OPENPICTURECpicRect) 
REM 
REM ‘BEGIN’ А 'MACDRAW^ PICTURE 
REM 
CALL PICCOMMENTCpicDwgBeg$,noData$,NIL&) 
IF Ғі1е%-2 THEN “poly2’ 
REM 
REM * CREATE 'MACDRAW-TYPE^ CLOSED-POLYGON * 
REM 
“poly!” 
CALL PICCOMMENT(PolyBegin&, пораѓа, NIL&) 
CALL PICCOMMENTCpicP1yC 10%, noDataZ, NIL&) 
CALL MOVETOC85, 10) 
CALL LINETOC85, 45) 
CALL LINETOC 184,70) 
CALL LINETOC225, 10) 
CALL LINETOC 135,35) 
CALL LINETOC85, 18) 
CALL PICCOMMENT (Po lyEnd% ,noData%, NIL&) 
GOTO *EndPicture^ 
REM 


REM * * х CREATE CONVENTIONAL CLOSED-POLYGON * х х 


é File Edit Commend Reine: 
Double Precision from 8 to 240 Digits 
Single Precision from 2 to Double-2 Digits 
Scientific Precision Digits from 2 to Double 
Maximum File Buffers Open 0 to 99 
Rounding Number 0 to 99 
Default Application and File ‘Creator сее 
Defauit Data File TYPE' Zedcor, Inc. 


Default Variable Type: @ Single Prec. © Integer 
© Double Prec. O Long Integer 
Ves No Ves No 
О @Test Array Bounds & O Space Req. After Key Words 


O @Test String Lengths © QG Convert to Upper Case 


О @Application Bundle Bit О @ Array Base 1 
O @ Expert Programmer Mode © QGLocete V,H 


Fig. 11 ZBasic 3.03 Configuration 


PolyHandle&-FN OPENPOLY 
CALL MOVETOC85, 10) 
CALL LINETO(C85, 45) 
CALL LINETOC 184,70) 
CALL LINETO(C225, 10) 
CALL LINETOC 135,35) 
CALL LINETOC85, 10) 
CALL CLOSEPOLY 
CALL FRAMEPOLY (Po lyHand1e& ) 
CALL KILLPOLYCPolyHandle&) 
REM 
REM ‘END’ А 'MACDRAW^ PICTURE 
REM 
*EndP icture^ 
CALL PICCOMMENT(picDwgEnd&, noData$, NIL&) 
REM 
REM CREATE THE ‘MACDRAW’ PICT FILE 
REM 


DEF OPEN "PICTMDRW^ 
IF File$21 THEN OPEN “0”,#1, “MacDraw.poly 1" 
IF Ғі1е%-2 THEN OPEN "05,81, "MacDrew .poly2" 
REM 
REM WRITE-OUT А 512 BYTE (256 WORDS OR INTEGERS) HEADER OF 
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ZEROES 


REM 
А4-0 
FOR 15-1 TO 256 
WRITE #1,А$ 
NEXT I$ 

REM 


REM CLOSE THE PICTURE & WRITE-OUT THE 'PICT^ DATA 
REM 

CALL CLOSEPICTURE 

PicPtr&=PEEK LONGCPicHand&) 

PicLengthS=PEEK WORDCPicPtr&*0) 

NumWords%=P icLength%/2 

doub leNumWords%=2*NumWords% 

IF doubleNumWords%<PicLength% THEN 
NumWords%=NumWords&+ 1 

FOR I%=1 TO NumWords% 

J83-2*CI$- 1) 

AZ=PEEK WORDCPicPtr&*Jg) 

WRITE #1, A% 

NEXT I$ 

CALL KILLPICTURECP icHaend& ) 

CLOSE #1 

NEXT File% 

END 


Ihe MacDrawPat Program 


REM 

REM (MacDrawPat .BAS) 

REM 

REM CREATES А ‘MACDRAWCPICT)’ GRAPHICS-DEMO FILE 
REM 


WINDOW OFF 
COORDINATE WINDOW 
REM 
REM DEFINE 'SHORT^ PICCOMMENTS 
REM 
NIL&=8 
noDate$-0 
picDwgBeg%= 130 
p icDwgEnd%= 131 
REM 


REM READ-IN ALL 36 'MACDRAW^ FILL/PEN PATTERNS AS HEX STRINGS 
REM 

DIM MacDrawPat$(36) 

FOR 1%-1 TO 36 

READ patID%, MacDrawPat$¢ IZ) 

NEXT 1% 
REM 
REM DEFINE PICTURE RECTANGLE СА FULL-SIZE 'MACDRAW^ PAGE) 
REM 

рісКесіг0. 

рісТор%-0 

picLef t%=0 

picBot tom$=726 

picRight%=576 


REM 
REM ‘INITIALIZE’ QUICKDRAW RECTANGLE 
REM 
DIM бесі, qdTop%, qdLeft%,qdBottom%, qdRight% 
REM 
REM ‘INITIALIZE’ QUICKDRAW ‘FILL’ PATTERN 
REM 
DIM fillPat, row 12%, row34%,row56%, row/8% 
f illPatPtr&zVARPTRCf illPat) 
REM 
REM ‘INITIALIZE’ PICTURE 
REM 


CALL 
SETRECTCpicRect,picLef t$ picTop%, picRight%, picBottom%) 
REM 
REM * x * CREATE A GRAPHICS-DEMO FILE * х х 
REM 
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PicHand&=FN OPENPICTURECpicRect) 


REM 
REM ‘BEGIN’ А ‘MACDRAW’ PICTURE 
REM 
CALL PICCOMMENT(picDwgBegS, пораїа$, NIL&) 
REM | 
REM TURN ON THE ‘PEN’ SO WE CAN SEE WHAT’S HAPPENING 
REM 
CALL SHOWPEN 
REM 
REM DRAW A ‘SINGLE-WEIGHT’ LINE 
REM 
CALL MOVETO(25, 25) 
CALL LINETOC325, 125) 
REM 


REM CREATE А 'FILLRECT^ - NOTE: FILL & FRAME ARE ‘GROUPED’ 


qdTop%=25 

qdLef t2-50 

QdBot tom%= 125 

ДОК ightZ= 100 

CALL 
SETRECTCqdRect , qdLef t$ , qdTopS , qdRight%, qdBot tom) 

CALL STUFFHEXCf illPetPtr&,MacDrawPat$C 1122 

CALL FILLRECTCqdRect, f ilIPat) 

CALL FRAMERECTCqdRect) 


REM 
REM CREATE А 'FILLOVAL^ - NOTE: FILL & FRAME ARE ‘GROUPED’ 
REM 
qdTop$225 
qdLef 122250 
adBot tom%=125 
qdRight%=300 
CALL 
SETRECTCqdRect, qdLef t%, qdTop%, qdR ight$ , qdBot от) 
CALL STUFFHEXCf illPatPtr&,MacDrawPat$C342) 
CALL FILLOVALCqdRect, f illPat) 
CALL FRAMEOVALCqdRect ) 


REM 
REM DRAW A ‘DOUBLE-WEIGHT’ LINE 
REM 
PEN 2,2,,, 
CALL MOVETO(25, 125) 
CALL LINETO(325, 25) 
CALL PENNORMAL 
REM 


REM CREATE А 'FILLROUNDRECT^ - NOTE: FILL & FRAME ARE 
‘GROUPED ’ 
REM 

qdTop%=25 

qdLef tZ= 150 

qdBot tom%=125 

ДОК ight%=208 

CALL 
SETRECTCqdRect, qdLef t$, qdTop%, qdRight%, qdBot tom ) 

ova lWidthZ= 10 

ova lHe ightZ= 10 

CALL STUFFHEXCfi11PatPtr&, MacDrawPat$(3d)) 

CALL 
FILLROUNDRECTCqdRect, ova Width$, ovalHeight&, fil1Pat) 

CALL FRAMEROUNDRECTCqdRect , ovalWidth%, ovalHeight%) 


REM 
REM DRAW A 'SINGLE-WEIGHT^ LINE 
REM 
CALL MOVETOC25, 150) 
CALL 1 ІМЕТ0(325,250) 
КЕМ 


REM CREATE А ‘PAINTRECT’ - NOTE: PAINT & FRAME ARE NOT! 
‘GROUPED ’ 
REM 

qdTop%= 150 

qdLef t%=58 

qdBot tom%=250 

qdR ightZ= 100 
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CALL 
SETRECTCqdRect, qdLef t$, qdTop$, qdRight%, даво бом) 


CALL PAINTRECTCqdRect) 

CALL PENNORMAL 

CALL FRAMERECTCqdRect ) 
REM 
REM CREATE А 'PAINTOVAL^ - NOTE: PAINT & FRAME ARE NOT! 
“GROUPED ’ 
REM 

qdTop%= 150 

qdLef t$2250 

qdBot tom%=258 

qdRight$2300 

CALL 
SETRECT(CqdRect, qdLef t%,qdTop%, qdRight%, qdBottom? ) 

PEN 2,2,,,3T 

CALL PAINTOVALCqdRect ) 

CALL PENNORMAL 

CALL FRAMEOVALCqdRect ) 


REM 
REM DRAW А 'DOUBLE-WEIGHT^ LINE 
REM 
PEN 2,2,,, 
CALL MOVETOC25, 250) 
CALL LINETOC325, 150) 
CALL PENNORMAL 
REM 
REM CREATE А 'PAINTROUNDRECT^ - NOTE: PAINT & FRAME ARE NOT! 
‘GROUPED ’ 
REM 
qdTop%= 150 
qdLef t= 150 


qdBot tom%=258 

QdR ight%=288 

CALL 
SETRECTCqdRect, qdLef t%,qdTop%, qdRight%, qdBottoms ) 

ova lWidth%=108 

ova lHe ightZ= 10 

PEN ,,,,32 

CALL PAINTROUNDRECT(CqdRect, ovalWidth%, ovalHeight%) 

CALL PENNORMAL 

CALL FRAMEROUNDRECTCqdRect, ovalWidth%, ovalHeight%) 
REM 
REM RESET THE ‘PEN’, DUE TO THE 'SHOWPEN^ CALL 
REM 

CALL HIDEPEN 


REM 
REM ‘END’ А ‘MACDRAW’ PICTURE 
REM 
*EndPicture^ 

CALL PICCOMMENTCpicDwgEnd$,nnoData$ , NIL&) 
REM 
REM CREATE THE ‘MACDRAW’ PICT FILE 
REM 

DEF OPEN "PICTMDRW^ 

OPEN “0”,81, “MacDraw.demo” 
REM 


REM WRITE-OUT А 512 BYTE (256 WORDS OR INTEGERS) HEADER OF 
ZEROES 


REM 
A30 
FOR I$-1 TO 256 
WRITE #1, АЯ 
NEXT 15 

REM 


REM CLOSE THE PICTURE & WRITE-OUT THE 'PICT^ DATA 
REM 
CALL CLOSEPICTURE 
PicPtr&-PEEK LONGCP icHand&) 
PicLengthZ=PEEK МОВОСРісРіг&+0 ) 
NumWords%=P icLength2/2 
doub leNumWords%=2*NumWords% 
IF doubleNumWords%<PicLength% THEN 
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NumWords%=NumWords&+ 1 
FOR I%=1 TO NumWords$ 
J¥=2*( 18-1) 
AZ=PEEK WORDCPicPtr&*J$) 
WRITE #1, AZ 
NEXT 1% 
CALL KILLPICTURECP icHand&) 
REM 


REM * X X X X X X X X X X X X X X X X X X X X X X X X X X Xx X 


x **X*X 

REM 

REM DATA FOR ALL 36 “МАСОВАН? FILL/PEN PATTERNS AS HEX 

STRINGS 

REM 
DATA 1,”0000000000000000" 
DATA 2,%0000000000000000" 
DATA 3,"FFFFFFFFFFFFFFFF^ 
DATA 4, *7700770077007700* 
DATA 5, “AASSAASSAASSAASS” 
DATA 6, *8822882288228822" 
DATA 7, *8800220088002200" 
DATA 8,”8000080080000800" 
DATA 9,%8000000008000000" 
DATA 10, “80804 13E0808 14Е3" 
DATA 11, FF808080FF080808" 
DATA 12,^814224188 14224 18" 
DATA 13, “884828 1008040201" 
DATA 14, ^E97038 1С0Е0783С1" 
DATA 15, ”77ВВ00ЕЕ778В00ЕЕ” 
DATA 16, “884422 1188442211" 
DATA 17, *99СС663399СС6633" 
DATA 18, ^2040800008040200" 
DATA 19, "FFOOFFOOFFOOFF 00" 
DATA 20, "FFOO0000FF000000" 
DATA 21, *CC00000033000000" 
DATA 22, “FOF SFOFOOFOF OF OF” 
DATA 23, "FF888888FF888888" 
DATA 24, “AA44AA 11АА44АА 11" 
DATA 25, "01020408 10204080" 
DATA 26, ”83070Е 1С3870Е061" 
DATA 27, “ЕЕООВВТТЕЕООВВТТ" 
DATA 28,” 11224488 11224488" 
DATA 29, *3366СС993366СС99" 
DATA 30, *40А00000040А0000" 
DATA 31, "AAAAAAAAAAAAAAAA" 
DATA 32, ”8888888888888888" 
DATA 33, "010110100 18 118 10" 
DATA 34, "0008 142А552А 1408" 
DATA 35, “ҒҒ80808080808080" 
DATA 36, “824428 1028448201" 
END 


Ihe MacDrawFiles Program 


REM 

REM (MacDrawF iles.BAS) 

REM 

REM CREATES А ‘MACDRAWCPICT)’ TEXT-FILE & GRAPHICS-F ILE 
REM 

REM REFER TO Macintosh Technical Note 827: MacDraw’s PICT 
File 

REM Format and Comments, August 28, 1986 BY Ginger Jernigan; 
REM 321: QuickDraw’s Internal Picture Definition, June 20, 
1986 

REM BY Ginger Jernigan; AND 891: Optimizing for the Laser- 
Writer 

REM -Picture Comments, March 2, 1987 BY Ginger Jernigan 
REM 

REM DISABLE ZBASIC’S DEFAULT WINDOW 


WINDOW OFF 
REM SET THE COORDINATE SYSTEM TO WINDOW 'PIXEL^ COORDINATES 
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REM 
REM 
REM 


REM 
REM 
REM 


COORDINATE WINDOW 
ESTABLISH A ‘STATUS’ WINDOW 


WINDOW 81, “MacDrawF iles.BAS”, (4,4 1)-(586,337), 261 
CALL MOVETOC 144,50) 
PRINT “Now creating the ‘MacDraw’ files...” 


DEFINE 'SHORT^ PICCOMMENTS 


NIL&=0 
побаіг%-0 
ріс0мдВед&= 130 
рісбидЕга%> 131 
Ро1уВедіп%- 160 
PolyEnd%= 161 
picPlyClof-165 


READ-IN SELECTED FONT FAMILIES 


DIM fontNo%¢ 132, fontName$C 13) 
FOR 18=1 TO 13 

READ fontNo&( 1%), fontName$C 1%) 
NEXT I8 


READ-IN ALL 8 'MACDRAW^ FONT SIZES 


DIM fontSize%(8) 
FOR I$21 TO 8 
READ fontSize%( IZ) 
NEXT 1% 


READ-IN ALL 6 ‘MACDRAW’ FONT STYLES 


DIM fontStyle&(6), fontStyle$(6) 
FOR 15-1 TO 6 

READ fontStyle&( 18), fontStyle$¢ 1s) 
NEXT I$ 


READ-IN ALL 36 'MACDRAW^ FILL/PEN PATTERNS AS HEX STRINGS 
DIM MacDrawPat$(36) 
FOR I%=1 TO 36 
READ patID%, MacDrawPat$¢ 1%) 
NEXT 1% 
READ-IN ALL 5 'MACDRAW^ LINE WEIGHTS 
DIM penWidth%(5),penHe ight%(5) 
FOR 1%=1 TO 5 
READ penWidth%C 1%), penHe ight%¢ 1%) 
NEXT I$ 
DEFINE PICTURE RECTANGLE СА FULL-SIZE 'MACDRAW^ PAGE) 
рісКесі-0. 
рісТор%-0 
picLef t3-0 
picBot tom%=720 
picRight%=576 
‘INITIALIZE’ QUICKDRAW RECTANGLE 
DIM qdRect,qdTop%, qdLeft%, qdBot оп, qdRight% 
‘INITIALIZE’ QUICKDRAW ‘FILL’ PATTERN 


DIM #111Раё, row 12%, row34%,row56%, row/8% 
f illPaetPtr&-VARPTRCf illPat) 


‘INITIALIZE’ PICTURE 
CALL 


SETRECTCpicRect,picLef t%, picTop%, picRight%, picBot tomZ) 
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REM 
REM CREATE A ‘MACDRAW’ TEXT-DEMO FILE & A GRAPHICS-DEMO FILE 
REM 
FOR File%=1 TO 2 
PicHand&=FN OPENPICTURECpicRect) 
REM 
REM ‘BEGIN’ A ‘MACDRAW’ PICTURE 
REM 
CALL PICCOMMENT(picDwgBeg%, пораѓа, NIL&) 
REM 
REM CHECK FOR TEXTCFileS=1) OR GRAPHICSCF i1e$22) 
REM 
IF File%=2 THEN “graphics” 
REM 
REM . . CREATE TEXT FILE... 
REM 
“text” 
REM 
КЕМ * * ‘SAMPLE’ FONT FAMILIES (USE 12 PT BOLD) * * 
REM 
x£$- 10 
FOR I$21 TO 13 
,%-25%(1%%10 
CALL MOVETOC x, u$ ) 
TEXT fontNo&(1%), fontSize%(3), fontStyle%(2), 1 
CALL DRAWSTRINGCfontName$¢1%)) 
CALL DRAWSTRINGC” 12 pt Bold’) 
NEXT I$ 
REM 
REM * * ‘SAMPLE’ FONT STYLES CUSE ‘HELVETICA’ 12 PT) * * 
REM 
x$- 180 
FOR 1%=1 TO 6 
y%=25*(1%+1) 
CALL MOVETOCx£, u$) 
TEXT fontNo$(4),fontSizeSC3),fontStyle$ CIS), 1 
CALL DRAWSTRINGCfontName$ C42) 
CALL DRAWSTRINGC^ 12 pt ^) 
CALL DRAWSTRINGCfontStyle$CIS2) 
NEXT I$ 
yi-y3*25 
CALL MOVETOCx%, u$) 
Style$-0 
Style$="" 
FOR I%=2 TO 6 
StyleZ=Style&+fontStyle%C1%) 
Style$=Style$+fontStyle$CIZ)+" * 
NEXT I$ 
TEXT fontNo&(4), fontSize%(3),Stylef, 1 
CALL DRAWSTRINGCfontName$ C42) 
CALL DRAWSTRINGC^ 12 pt 4 
CALL DRAWSTRINGCStyle$) 
REM 
REM * * ‘SAMPLE’ FONT SIZES CUSE ‘HELVETICA’ BOLD) * * 
REM 
x$- 10 
yo 1d¥=39 1 
FOR 1%-1 TO 8 
yZ=yold%+fontS ize%C 1%) 
yo 1d%=y% 
CALL MOVETOCx%, u$) 
TEXT fontNo%(4), fontSize%C 1%), fontStyle$(2), 1 
CALL DRAWSTRINGCfontName$¢4 )) 
CALL DRAWSTRING(^ ^) 
Size$=STR$CfontSize%C18)) 
CALL DRAWSTRING(Size$) 
CALL DRAWSTRINGC^ pt Bold”) 
NEXT I$ 
GOTO *EndPicture^ 
REM 
REM . . CREATE GRAPHICS FILE... 
REM 
“graphics” 
REM 
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REM 
REM 
REM 


* х 'SAMPLE^ ALL 36 'MACDRAW^ FILL PATTERNS * * 
NOTE: FILL & FRAME ARE 'GROUPED^ AUTOMATICALLY 


FOR I$21 TO З 
qdBottont-20 

FOR J%=1 TO 12 
K8-CIS- 1)* 12*J8 
qdTop$-qdBot tons +5 
qdLef t$» 19*CIS- 1)*30 
qdBottonSsqdTop$*25 
qdRightS-qdLef t%+25 
CALL 


SETRECT(qdRect, qdLef t£, qdTop8, qdR ight, qdBot tont) 


REM 
REM 
REM 


REM 
REM 
REM 


REM 
REM 
REM 


REM 


CALL STUFFHEXCf i TIPetPtr&,MacDrewPet$CK22) 
IF K3» 1 CALL FILLRECTCqdRect, ?і11Раё) 

CALL FRAMERECTCqdRect ) 

NEXT J% 

NEXT 1% 


ж ж ‘SAMPLE’ ALL 5 ‘MACDRAW’ LINE WEIGHTS * * 


TEXT fontNoS (4), fontSize&¢ 1), fontStyle&(2), 1 
xB= 150 

FOR I%=1 TO 5 

y$- 10+30*18 

CALL MOVETOCxS, у4) 

Width$sSTR$Cpen idthECIS2) 
Height$-STRÉCpenHe ight C182) 

Note$s^ Line Width, Height = “+Width$+”, "*Height$ 
CALL DRAWSTRINGCNote$) 

CALL MOVEC 10, -penHe ight£ C182) 

CALL PENSIZECpenWidth&(18), penHeight&(18)) 
CALL LINEC41-penWidthiCI3),0) 

CALL PENNORMAL 

NEXT I$ 


* * ‘SAMPLE’ ALL 3 ‘MACDRAW’ ARROWHEADS * * 
USE HORIZ LINES 


dx%=59 
dy$-0 
х%5-090 


USE RIGHTCI%=1), LEFTCIZ=2), & ВОТН(1%-3) ARROWHEADS 


FOR І5-1 TO 3 
xB=x%+65 


USE ALL 5 LINE WEIGHTS 


FOR J%=1 TO 5 

у%= 150*30*J8 

CALL PENSIZECpenWidth%(U%), penHeight%(J%)) 
xah] 1%=x% 

yah] 1%=y% 

x&h128zx8*dx$ 

yeh128syX д 


ADJUST LENGTHS FOR PENSIZE 


IF 18=1 THEN хаһ12%=хаһ12%+ 1-penWidth$(J$) 
IF 1%=2 THEN хәһ11%-хаһҺ1 1%+ 1 

АггиР1%=1% 

60508 “ArrowHeads” 

NEXT J3 

NEXT 1% 


USE VERT LINES 
dx$20 


dy$:50 
y8-210 
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REM USE RIGHTCIZ=1), LEFTC1%=2), & BOTHCI%=3) ARROWHEADS 


REM 


REM 
REM USE 
REM 


REM 


FOR I%=1 TO 3 


y=y%+65 
ALL 5 LINE WEIGHTS 


FOR J%=1 TO 5 


х5-140%30%,% 

CALL PENSIZECpenWidth%CJ%), penHe ight%C US) >) 
xah] 1%-х% 

yah] 1%=y% 

xah1222x$*dx8 

yah123298*du$ 


REM ADJUST LENGTHS FOR PENSIZE 


REM 


IF I$02 THEN yah] 1%-уаһ1 18-1 

IF I%=1 THEN yah]2%=yah12%-penHe ight%CJ%) 
ArrwPt%=I% 

GOSUB “ArrowHeads” 

NEXT J8 

NEXT I$ 


REM USE 45 DEG. LINES 


REM USE 


REM USE 


REM 


dx$- INTC50. /SQRC2. 2) 
dyS- INTC5. /SQRC2. )) 
у4-490 


RIGHTCI#=1), LEFTCIZ=2), & ВОТН(1%-3) ARROWHEADS 


FOR I$21 TO 3 
yS=yS+50 


ALL 5 LINE WEIGHTS 


FOR JZ=1 TO 5 

x$5125*30*J8 

CALL PENSIZECpenWidth$CJ$), penHeight8CJ$)) 
xah] 15-х% 

yah] 1%8-,% 

xah1232x2$*dx$ 

yah 12%=y%+dy% 


REM ADJUST LENGTHS FOR PENSIZE 


REM 


“df 1” 


“df 2” 


“df 3^ 


IF I$21 THEN “df i^ 

IF 1222 THEN *df2^ 

GOTO *df3^ 
x&h123-xah122$- 1- INTCpenWidth2 CJ$ ) /SQRC2. 2) 
yeh 12%=yah12%- 1- INTCpenHeight£CJ$ )/SQRC2. 2) 
IF J%<5 THEN “df3” 

хаһ12%=хаһ12%+ 1 

yah 12%=yah12%+ 1 

GOTO “043” 

xah] 18=хәһ1 18+ 1* INTCpenWidth$ CJ8) /SQRC2.2) 
yah] 1%=yah1 18+ 1+INTCpenHeight%CJU%)/SQRC2. 2) 
IF J$«3 THEN *df3^ 

xah] 1%-хаһ1 18-1 

yah] 1$zyah1 13-1 

IF J$«5 THEN *df3^ 

хаһ1 1#=хаһ1 18-1 

yah] 1%=yah] 1%- 1 

ArrwPt$-18 

GOSUB "ArrowHeads^ 

NEXT J$ 

NEXT I$ 

CALL PENNORMAL 


REM 
REM * * 'SAMPLE^ ALL 36 ‘MACDRAW’ PEN PATTERNS * * 


REM 


CALL PENSIZECpenWidth%(5), penHeight%(5)) 
FOR 1%-1 TO З 
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y%=5 

FOR JZ=1 TO 12 

К#=(18- 1) 12*J8 

x%=385+(1¥- 1)*50 

%5-,%%30 

CALL MOVETOCx$, yS) 

CALL STUFFHEXCfi11PatPtr&,MacDrawPat$(K% 2) 
CALL PENPATCfi11Pat) 

CALL LINEC40,0) 


NEXT J3 
NEXT I$ 
CALL PENNORMAL 
REM 
REM * * ‘SAMPLE’ ALL 8 GRAPHICS ‘TOOLS’ * * 
REM 
CALL PENSIZECpenWidth%(3),penHe ight%(3)) 
REM 
REM USE ORTHOGONAL LINES 
REM 
CALL MOVETOC 10, 420) 
CALL LINETO(C50, 420) 
CALL MOVETOCB80, 400) 
CALL LINETOC8@, 4402 
CALL MOVETOC 110, 400) 
CALL LINETOC 158, 440) 
REM 
REM USE UNCONSTRAINED LINES 
REM 
CALL MOVETOC 12, 450) 
CALL LINETOC75, 490) 
CALL MOVETOC85, 4902 
CALL LINETOC 158, 450) 
REM 
REM USE RECTANGLES 
REM 
qdTop%=5 10 
qdLef t%=18 


QdBot tomB=qdTop%+48 
аак ightZ=qdLef t$*40 


CALL 
SETRECTCqdRect, qdLef t$ , qdTop$, qdRight%, qdBot toms ) 

CALL FRAMERECTCqdRect ) 

qdTop$-520 

qdLef t%=60 

qdBottomn$-qdTop$*20 

QdR ight=qdLef t$*60 

CALL 


SETRECTCqdRect, qdLef t%,qdTop%, qdRightZ, qdBot (оп ) 
CALL FRAMERECTCqdRect ) 
qdTop%=588 
qdLef t3- 130 
qdBottomS-qdTop$*60 
qdRightS-qdLef t%+20 
CALL 
SETRECTCqdRect, qdLef t$ , qdTop$, qdRight%, qdBottomZ ) 
CALL FRAMERECTCqdRect ) 
REM 
REM USE ROUNDED-CORNER RECTANGLES 
REM 
ova lWidth3=20 
ovalHe ightZ=20 
даТор%-580 
qdLef t$- 10 
qdBottomS-qdTop$*40 
qdRightS-qdLef t3*40 
CALL 


SETRECTCqdRect, qdLef t$ , qdTop£ , qdRight%, qdBot toma ) 
| CALL FRAMEROUNDRECT CqdRect, ovalWidth%, ovalHeight%) 
qdTop%=598 
qdLef t%=69 
qdBottom=qdTop%+28 
адк ight%=qdLef t$*60 
CALL 
SETRECTCqdRect, qdLef t%,qdTop%, qdRight%, адво ол) 
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CALL FRAMEROUNDRECT(qdRect, ovalWidthS, ovalHe ightS) 


adTop%=578 
qdLef tZ= 130 

qdBot tomZ=qdTop%+68 
qdR ightZ-qdLef 1%%20 
СА 


LL 
SETRECTCqdRect, qdLef t£, аатор, qdR ight$ , qdBot tom ) 


CALL FRAMEROUNDRECTCqdRect , ova Width, ovalHe ight) 


REM 

REM USE OVALS 

REM 
qdTop%=658 
qdLef = 10 


qdBottonZ-qdTop$*40 

qdR ightS-qdLef t$*40 

CALL 
SETRECTCqdRect , qdLef t$, аатор, qdRightZ, qdBot {оа ) 

CALL FRAMEOVAL CqdRect ) 

qdTop$-660 

adLef t£=69 

qdBot tomZ=qdTop%+28 

аак ight%=qdLef 15:60 

CALL 
SETRECTCqdRect , qdLef t£, аатор, qdRightZ, qdBot tom ) 

CALL FRAMEOVALCqdRect ) 

qdTop$2640 

qdLef t%= 130 

qdBot от =адтТор&+60 

qdR ightSzqdLef t$420 

CALL 
SETRECTCqdRect , qdLef t$, qdTop%, qdRightZ, qdBot toma ) 

CALL FRAMEOVALCqdRect ? 


REM 

REM USE ARCS 

REM 
startAngle$-225 
arcAngle%= 150 
qdTop%=4 10 


qdLef t$2385 

саво tom%=qdTop%+49 

QdR ightZ-qdLef t$*49 

CALL 
SETRECTCqdRect, qdLef t$, qdTop$ , qdRight%, qdBot toma ) 

CALL FRAMEARCCqdRect , startAngle£, arcAngleZ) 

qdTopS2420 

qdLef t$2435 

qdBottonS-qdTop$*20 

qdR ightZ=qdLef t%+60 

CALL 


SETRECTCqdRect, qdLef t$, qdTop%, qdR ight£ , qdBot toma ) 
CALL FRAMEARCCqdRect , startAngle%, arcAngleZ) 
аЧТор%=400 
qdLef {#=505 
qdBot tom£=qdTop%+60 
qdR ightSzqdLef t$420 
CALL 

SETRECTCqdRect , qdLef t$, аатор, qdRight%, qdBot tom ) 
CALL FRAMEARCCqdRect , stertAngle$ , arcAngleZ) 

REM 

REM USE THE ‘FREEHAND’ TOOL C'MACDRAW^ USES A POLYGON) 

REM 
PolyHendle&-FN OPENPOLY 
PI=4.*ATNC1.) 

РІ020=РІ/20. 

ТНЕТА=0. 
К-50.%005(2.%ТНЕТА) 
X$2455* INTCR*COSCTHETA2) 
Y$-510* INTCR*SINCTHETA2) 
CALL MOVETOCXS, Y$ 

FOR I$21 TO 20 
ТНЕТА>1%%Р1020 
=50.*COS(2. *THETA) 
X%=455+INTCR*COSC THETA) ) 
Y%=5 1O+INTCR*S INC THETA)) 
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CALL LINETOCXS, YS) 
NEXT I$ 
CALL CLOSEPOLY 
CALL FRAMEPOLYCPolyHandle&) 
CALL KILLPOLY(CPolgHandle&) 
REM 
REM USE А POLYGON 
REM 
PolyHandle&sFN OPENPOLY 
CALL MOVETOC385 , 540) 
CALL LINETOC385,575) 
CALL LINETOC 485, 689) 
CALL LINET0(525, 549) 
CALL LINET0C435, 565) 
CALL CLOSEPOLY 
CALL FRAMEPOLYCPolyHandle&) 
CALL KILLPOLYCPolyHandle&) 
REM 
REM USE A ‘FORCED-CLOSE’ POLYGON 
REM NOTE: THE ‘PICCOMMENTS’ WILL FORCE CLOSURE 
REM 
CALL PICCOMMENTCPolyBegin$,noData$,NIL&) 
CALL PICCOMMENTCpicP1gC1of,noData$,NIL&) 
CALL MOVET0C385, 610) 
CALL LINETOC385, 645) 
CALL LINETOC 485,678) 
CALL LINETOC525, 618) 
CALL LINETOC 435, 635) 
CALL LINETOC385, 610) 
CALL PICCOMMENT (Po lyEnd%, пораѓа, NIL&) 
CALL PENNORMAL 


REM 
REM ‘END’ A 'MACDRAW^ PICTURE 
REM 
*EndPicture^ 
CALL PICCOMMENTCpicDwgEnd$, noDatas , NIL&) 
REM 
REM CREATE THE ‘MACDRAW’ PICT FILE 
REM 
CURSOR=4 
DEF OPEN *PICTMDORW^ 
IF FileZ=1 THEN OPEN *0^,31, ^MacDraw.text^ 
IF File$22 THEN OPEN “0”,81, ^MacDrew.graphics"^ 
REM 


REM WRITE-OUT А 512 BYTE (256 WORDS OR INTEGERS) HEADER OF 
ZEROES 
REM 

А4-й 

FOR 14-1 TO 256 

WRITE 91, АЯ 

NEXT 1% 


REM 
REM CLOSE THE PICTURE & WRITE-OUT THE 'PICT^ DATA 
REM 
CALL CLOSEPICTURE 
PicPtr&=PEEK LONGCPicHand&) 
PicLength%=PEEK WORDCPicPtr&*0) 
NumWords%=PicLength%/2 
doub leNumWords$-2*NumWords$ 
IF doubleNumWords%<PicLength% THEN 
NumWords%=NumWords& + 1 
FOR I%=1 TO NumWords% 
Ј=2%(18- 1) 
AZ=PEEK WORDCPicPtr&+JZ) 
WRITE 81,А% 
NEXT 1% 
CALL KILLPICTURECP i cHand&) 
CLOSE 81 
CURSOR-0 
NEXT File% 
GOTO “Exit? 
REM 
REM X X X X X X X X X X X X X X X X X X X X X X X X X X X X X 
xx x xk xX 
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“ArrowHeads” 
REM 
REM SUBROUTINE TO CONSTRUCT A ‘MACDRAW’ ARROWHEADCS) LINE 
REM 
REM DEFINE ARROWHEAD PARAMETERS 
REM 
DIM ArrwRect , ArrwRT%, ArrwRL%, ArrwRBS, ArrwRRE 
МІ %-0 
noDataz=8 
picArrwRZ= 170 
picArrwLl%=17 1 
рісАггиВ&= 172 
picArrwEnd%= 173 
агсАгд1е&=48 
REM 
REM GET PEN SIZE & ARROWHEAD RECTANGLE SIZE 
REM 
DIM pnLocV£, pnLocH$, pnSizeV%, pnSizeH$, pnModes 
DIM pnPat 128 ,рпРаї348 ,рпРаї56& ,pnPat788 
CALL GETPENSTATECpnLocV£ ) 
IF pnSizeV$-0 THEN RETURN 
IF pnSizeV$-1 THEN ArrwWH%=20 
IF pnSizeV$-2 THEN ArrwWH$-30 
IF pnSizeV%=4 THEN ArrwWH%=49 
IF pnSizeVZ=6 THEN ArrwWH$-50 
REM 
REM DETERMINE LINE PROPERTIES 
REM 
Чхаһ1=хаһ12%-хаһ1 1% 
dyah]=yah12%-yah] 1% 
lineLengthzSQRCdxeh*dxah!*dyah1*dyahl) 
xcorr£sINTCCdyahl /1ineLength)*pnS izeV%/2) 
ycorr%=INTCABSCdxah1/1ineLength)*pnS izeVZ/2) 
IF хаһ11%-хаһ12% THEN “ahi” 
tanAng 1н-дуаһ1 /dxah] 
Ang le=57 .2957795*A TNC tanAngle) 
IF xahl1%>xahl2% THEN Angle=Angle+ 180. 
lineAngle%=INTCAngle)+98 
GOTO “ah3” 
*ah 1^ IF yah) 1%>yahl2% THEN ”аһ2” 
lineAngle%=98+98 
GOTO *ah3^ 
“аһ2” lineAngle$--90:*90 
REM 
REM DETERMINE WHICH ARROWHEADCS) TO DRAW 
REM (CArrwPt%=1 FOR PT 1, 2 FOR 2, З FOR BOTH) 
REM 
“ah3” — shortsCArrwWH2/2)/lineLength 
IF ArrwPt$-2 THEN “ah4” 
REM 
REM ARROWHEAD AT PT 1 
REM 
bo thF 180851 
xahlc$-xahl 1% 
yah lc%=yah] 1% 
xah11$2xahlc$* INTCshort*dxahl) 
yeh] 1%=yah1c%+ INTCshort*dyah] 2 
star tAng]e%=1 ineAngle%-arcAngle%/2 
IF хәһ11%>х8һҺ12% THEN “аһб* 
IF хаһ11%<хаһ12% THEN “ahd” 
IF yah] 1%>yahl2% THEN “аһб” 
GOTO “ahd” 
REM 
REM ARROWHEAD AT PT 2 
REM 


*ah4^ bothF 1893-2 
xahlc$-2xah1258 
yehlc$-yah1258 
xah12%=xah1c%- INTCshort*dxah]) 
yah 12%=yah1c%- INT Cshor t*dyah] 2 
star tAng]e%=1 ineAngle%+ 188-arcAngle%/2 
IF startAngle%)360 THEN startAngleZ=star tAng]e%-360 
IF хаһ11#‹хаһ12% THEN *ah6^ 
IF хаһ11#›хаһ12% THEN “аһ5* 
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IF yah] 18<yah12% THEN *аһб” 


“ahd” рісАгги&=рісАггиі $ 
IF ArrwPt$-3 THEN рісАгги&=рісАггиВ% 
GOTO “аһ7” 
ahó” picArrw%=p icArrwR% 
IF ArrwPt%=3 THEN picArrw%=picArrwB% 
REM 


REM ‘QUICKDRAW’ THE ARROWHEADCS) WITH ‘PAINTARC’ & 
REM USE PICCOMMENTS TO ‘TIE’ ITCTHEM) TO THE LINE 
REM 

*ahT^ ArrwRTZ-gahlci-ArrwWHS /2 
ArrwRBE-ArrwRTS *ArrwWHS 
ArrwRLSzxahlcS-ArrwWHS /2 
ArrwRRS-ArrwRLS +ArrwWHS 


CALL 
SETRECTCArrwRect , ArrwRL&, ArrwRTS, ArrwRR&, ArrwRBE ) 
IF ArrwPt%<3 THEN *ah8^ 
IF bothFlag%<2 THEN “әһ8* 

GOTO “ahd” 

CALL PICCOMMENTCpicArrw%,noDataz, NIL&) 
CALL PAINTARCCArrwRect, star tAngleZ,arcAngle%) 
IF ArrwPt%<3 THEN “ah 10” 

IF bothFlag%<2 THEN “ah4” 

xah] 1$2xah11$-xcorr$ 

yah] 1%=yah] 1%-ycorrs 

хаһ12%-хаһ12%-хсоггА 

yeh123-yeh122-ucorr$ 

CALL MOVETOCxah] 1%, yah] 1%) 

CALL LINETOCxah12%, yah12%) 

CALL PICCOMMENTCpicArrwEnd&, noDataZ, NIL&) 
RETURN 


*ah8^ 
*ah9^ 


“ah 10^ 


REM 
REM X X X X X X X X X X X X X X X X X X X X X X X X X X X X X 


xx xx x 


REM 
REM DATA FOR SELECTED FONT FAMILIES 
REM 

DATA 9,*Chicago” 

DATA 22, "Courier^ 

DATA 3, “Geneva” 

DATA 21, “Helvetica” 

DATA 6, “London” 

DATA 4, “Monaco” 

DATA 15,°N Helvetica Narrow” 

DATA  2,"New York" 

DATA 16, "Palatino" 

DATA 23, “Symbol” 

DATA 20,“Тіпез” 

DATA 5,”Уепісе” 

DATA 18, "Zapf Chancery’ 
REM 
REM DATA FOR ALL 8 'MACDRAW^ FONT SIZES 
REM 

DATA 9 

DATA 10 

DATA 12 

DATA 14 

DATA 18 

DATA 24 

DATA 36 

DATA 48 
REM 
REM DATA FOR ALL 6 'MACDRAW^ FONT STYLES 
REM 

DATA @,*Plain Text” 
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REM 


DATA 1, *Bold’ 

DATA 2,"Italic^ 
DATA 4, "Under ine’ 
DATA 8,"Outline^ 
DATA 16, “Shadow” 


REM DATA FOR ALL 36 ‘MACDRAW’ FILL/PEN PATTERNS AS HEX 


STRINGS 
REM 


DATA  1,"0000000000000000" 
DATA 2,^0000000000000000" 
DATA 3,"FFFFFFFFFFFFFFFF^ 
DATA 4, *7700770077007700* 
DATA 5, ”АА5БАА55АА55АА55" 
DATA 6, “8822882288228822" 
DATA 7, "8800220088002200" 
DATA 8,^8000080080000800" 
DATA 9, "8000000008000000" 
DATA 10, "80804 13E0808 14E3" 
DATA 11, “ҒЕ808080ЕЕ080808" 
DATA 12, "814224 188 14224 18" 
DATA 13, "804020 100804020 1" 
DATA 14, ”Е070381С0Е0783С1” 
DATA 15, “77BBDDEE77BBDDEE” 
DATA 16, “884422 1188442211" 
DATA 17, ”99СС663399СС6633" 
DATA 18, ”2040800008040200" 
DATA 19, “FFOOFFOOFFOOFFOO" 
DATA 20, ”ҒҒ000000Е-000000" 
DATA 21, "CC00000033000000" 
DATA 22, “FOF OFOFOOFOF OF OF” 
DATA 23, "FF888888FFB88888" 
DATA 24, “AA44AA11AA44AA 11" 
DATA 25, "01020408 10204080" 
DATA 26, ”83070Е 1C3870E0C 1" 
DATA 27, "EEDDBBTTEEDDBBTT" 
DATA 28,” 11224488 11224488" 
DATA 29, ”3366СС993366СС99" 
DATA 30, *40AG2000040A0000" 
DATA 31, “АААААААААААААААА” 
DATA 32, “8888888888888888" 
DATA 33, "010110 100 10 110 10" 
DATA 34, "0008 142A552A 1408" 
DATA 35, "FF80808080808080" 
DATA 36, "824428 102844820 1" 


REM 
REM DATA FOR ALL 5 'MACDRAW^ LINE WEIGHTS 


REM 


*Exit^ 


DATA 0,0 
DATA 1,1 
DATA 2,2 
DATA 4,4 
DATA 6,6 


WINDOW CLOSE #1 
WINDOW #1, “MacDrawF i les .BAS”, С4,41)-С506, 337), 261 
TEXT 4,9,0,1 

CALL MOVETOC 162,58) 

PRINT “Both ‘MacDraw’ files created ! !^ 
CALL MOVETOC 174,65) 

PRINT “Hit [Return] to exit. . .^ 

BEEP 

INPUT ANS$ 

WINDOW CLOSE 81 

END 
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Basic School 
Text Edit Records from ZBasic 


How NOT to Do TextEdit 


In past months I promised you some more on text editing. I 
really intended to give youa text processor written completely in 
ZBasic. Well, this article is dedicated to the time that it took to 
find out what not to do if you plan on creating a full blown text 
processor. This column may not be all that was promised, but it 
should provide some help to those of you that don't know what 
to do with text edit routines. 


Basic or Toolbox? 


We have talked about text editing in some of the past issues 
(see June, 1987 and August, 1987). I'll try to pick up where we 
left off wherever that might be. There are two varieties of Basic 
programming. The soft approach uses only the enhanced Basic 
language provided by the language developer. These high level 
routines are short cuts that should save you time and increase 
your chances of getting your program to work quickly and 
efficiently. The other approach is the ROM calls approach. 
Effectively, the ROM approach is what C and Pascal program- 
mers have to do every time they write a program unless they have 
some preprogrammed “libraries” to set up scroll bars, windows, 
text edit fields etc. for you. (Maybe that’s the best approach). 
Ideally speaking, I think we want the best of both worlds. We 
want to be able to set up the basic functions with high level 
routines, but be able to have the capability (power) to call low 
level (ROM) routines when the capabilities of the high level 
routines are not sufficient. 


Basic Flunks Text Editing 


Why am I telling you all this? Well, I tell you this so you can 
be warned in advance of the limitations of thinking that the 
enhanced BASIC routines will always be good enough to do the 
job. Text Editing is one of these cases. The present capabilities 
of ALL Basic languages enhanced Basic commands are not 
enough to do text editing without relying on calls to the ROM 
routines. I am referring to the use of the EDIT FIELD statements 
in either MS Basic or ZBasic. In MS Basic you are limited to 8 
types of edit fields with no way to access the Text Edit record or 
to scroll the text in the edit field. The ScrollText Library call will 
allow you to do some limited scrolling, however, does not 
provide a way to cut and paste easily. (see The Complete 
MacTutor, Vol. 2, pg. 345 for examples of scrolling with MS 
Basic.) Since there has been no word from Microsoft in about a 
year (and no updates of MS Basic), Microsoft Basic is pretty 
much out of the running at the present time. 


430 


Dave Kelly 
MacTutor Editorial Board 
MacTutor Vol. 3 No. 11 


cBasic 


Language Preference 
APDA Survey 1985 


4% Other 


Lisp 4% 
Modula-2 4% 


Forth 4% 30% 
Basic 6% C 
20% 
Assembly 


28% 
Pascal 


Fig. 1 1985 APDA Survey of Preferred Languages 


Text editing in ZBasic is much more useful. ZBasic has 4 
types of Edit Fields (the text is always selected when default text 
is used). The best addition is the TEHANDLE function. 
TEHANDLE gives you the capability to get to the Edit Field’s 
textrecord. It sounds simple, but there are some other limitations 
that I might classify as bugs. Yes, I’ve found a bug, but don’t 
misunderstand me. ZBasic is a very sound product these days. 
The problems have resulted in my spending a lot of time search- 
ing out the best way not to do text editing. 


TEHandle Function in ZBasic 


First I will try to explain the usefulness of the TEHANDLE 
function. The example in the ZBasic manual, pg. E-141 demon- 
strates TEHANDLE, but the example is more useful for what it 
does than it is as an example of how to use TEHANDLE. In fact, 
the functions defined in the example can be cut and pasted into 
your Own program to allow you to pass EDIT FIELD strings 
longer than 255 characters (ZBasic’s limit). I recommend that 
you use these routines if you have a need to handle long strings. 
The definition of how TEHANDLE works is conspicuously 
missing. The top of the page says the format is just TEHANDLE 
with no parameters. In fact, TEHANDLE by itself gives a syntax 
error. A close look at the functions defined in the example show 
that the format should be: TEHANDLE (field ) where field is the 
field number. Here is what is confusing: The definition in the 
manual says that TEHANDLE “Returns the handle to the current 
EDIT FIELD...” and that the purpose is to be able to handle fields 
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larger than 255 characters. Well, I guess they didn't think that 
anyone would want to do more than that. 

The problem I have encountered is that TEHANDLE only 
works if the value of field is 1. That is, it only works for the first 
EDIT FIELD of a window. For instance, if you change the EDIT 
FIELD number of the example on page E-141 to 2 and adjust all 
the function calls such that they will also refer to field 2, the 
example program will gracefully bomb. Zedcor tells me they 
think there is a problem with some changes that were made with 
system version 4.1 and ZBasic 4.0. ZBasic 4.01 should soon be 
out. /Where have we heard that before? -Ed] 

For me, the importance of getting at the text edit record is to 
be able to add power to my program to control where the text is 
located, where it is viewed, what part of the text is selected, and 
even change fonts and size information (among other things). A 
text edit record is created for each EDIT FIELD you create. The 
record, shown on pg. E-183 of the ZBasic manual, is stored in the 
heap with other resources. It turns out however that it was not 
intended that the user have this kind of capability with ZBasic 
EDIT FIELDS. For example, if you have several EDIT FIELDS 
on your screen, you will have trouble changing fonts or font sizes 
in one field (by poking the font id into the edit record) without 
affecting the other fields or even the printing on the screen. It 
appears that the built-in automatic EDIT FIELD update routines 
won't let the text font or style change after it has been created. 
Another disappointment is that the EDIT FIELD automatic 
routines reset the text to the beginning of the window so that text 
scrolling is impossible (or very cumbersome). The bottom line 
is that the ROM routines will need to be used in full to really have 
control over what the EDIT FIELD does. 


Complications Set In... 


This leads us to another problem. If you use the TENEW 
function (ROM) to create the Text Edit Field the ZBasic DIA- 
LOG statement will not know how to tell the Dialog Event 
routine that a text edit event has occurred. Then how do you 
process the events? Well, how about GETNEXTEVENT ? 
(discussed in Sept. 1987 MacTutor). Hmm... butif I've got to go 
to all that trouble... why not just use Pascal and not have all the 
limitations that Basic leaves us with. Notonly that but the Pascal 
routines have been used hundreds of times before and there are 
a lot of examples available. Doesn't sound too promising for 
BASIC. Ithink that is why so many serious developers only use 
Basic occasionally for easy, short, quick routines. Take alook at 
the Mousehole Basic Only board and compare it with the Pascal 
or C board and you'll see whatI mean. In the August 1987 APDA 
catalog there is a graph on page 11 showing the results of a survey 
done in 1985. The results are that 30% prefer C, 28% prefer 
Pascal, 20% prefer assembler, 6% prefer Basic, 4% Forth, 4% 
Modula-2, 4% LISP, 4% Other. These results were before TML 
and Lightspeed Pascal became popular so there might be some 
changes to the high end of the scale. (See figure 1) 


So what do we do about it? Sit back and wait for Zedcor to 
improve their product. In this case, the limitations are created 
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" é Fite Edit б 


89885833233 


eMacTutor, 1987 


By Dave Kelly 
ZBasic Version 4.0 


Fig. 2 The Text Edit Record 


" é File Edit Ы 
mI E: TEdit Tour ШИЕ 


Fig. 3 Our Demo Program in Action 


only because Zedcor has not provided access to all routines via 
the high level enhanced BASIC routines. Fortunately, they did 
provide the ROM routine capability to do the job. The problem 
is that it will be just as much work to write a ROM program in 
BASIC as it would be in PASCAL. Zedcor still has the finest 
Basic available and they have thus far provided excellent support 
of the language. I realize that some of you have been upset that 
you have been the guinea pigs while the bugs were worked on. 
For those of you that have lost hope, you can be assured that 
ZBasic is now a solid product. 

The program I’ ve provided here is the results of my attempts 
to take the EDIT FIELD to its maximum capability. I refer to it 
asatour of the Edit Field because it gives you an overview of Edit 
Fields and Text Edit Records. The program is set up in a similar 
manner to the TEHANDLE example in the ZBasic manual pg. E- 
141 except that I have added the capability to view the entire text 
edit record and attempt to change the values of the edit record. If 
you type in the byte offset of the edit record (found on E-183) you 
сап see which of the parameters of the record can be changed and 
which ones change back when the EDIT FIELD is updated. 
Figure 2 shows the text edit record and is displayed as a menu 
function by the program. Figure 3 shows the program in action. 
A text edit window is put up, with the text edit fields displayed 
below. The program is supposed to work correctly on a large 


431 


screen (Mac II), but the default window size comes up and 
obscures some of the field information. 


Program Details 


First a window is opened to full screen size (same as your 
monitor). By calling GETWMGRPORT as Dave Smith sug- 
gested I’ve modified the routine from what was in the Sept. 1987 
MacTutor. Three EDIT FIELDS are opened. The firstis the main 
text edit field the other two are for convenience in entering data 
to change the text edit record. 

The SCROLL BUTTON statement was intended to be used, 
but has not been implemented. It appears that since the canned 
EDIT FIELD seems to reset itself to the first line of the text, 
TESCROLL cannot be used with EDIT FIELDs. You would 
have to create your own TE field with ROM calls. 

Generally speaking, the “MenuEvent” and “DialogEvent” 
routines don't change a whole lot from program to program. 
Since the EDIT FIELD is a canned function (preprogrammed, 
automatic function), it is not necessary to call any ROM routines 
to handle the basic functions of the EDIT FIELD. ZBasic handles 
calls like TEIDLE for you. The user defined function te- 
WordPeek% helps to shorten the typing involved in the text edit 
record list. 

There is a problem that I discovered in my early version of the 
program before I removed the growbox from the window. It 
seems that if you resize the window, the text that was printed with 
PRINT @ (x,y) does not print at x,y when the point x,y is outside 
the visible range of the window. The same can be said for the 
LOCATE statement. The solution would be to use the DRAW- 
STRING ROM call to draw the text at a specific location. 

The buttonevent routine is supposed to handle the reading of 
the byte to be changed and the new value. The problem here was 
that the TEHANDLE function would not work for a 2nd or 3rd 
EDIT FIELD. 

AS you can see, there is still a bit of work to be done here, if 
possible. From what I can tell here, I recommend that ROM calls 
be used for any major text editing. This will have to be followed 
up on in future issues of MacTutor. 


'Edit Field Tour 

‘A software explanation of the Text Edit Record 
"WARNING: Some portions of this progrem do not 
‘function properly. USE AT YOUR OWN RISK! 

‘the ZBasic way. 

'eMacTutor, 1987 

‘By Dave Kelly 


WINDOW OFF 


COORDINATE WINDOW 

DEF MOUSE =-1 

DIM DestRect%(3) 

CALL GETWMGRPORTCWMgrPor t&) 

‘Figure out the size of monitor used 

PortRecttop=PEEK WORD CWMgrPor t&+8 ) 

Por tRectleft=PEEK WORD CWMgrPor t&+ 10) 

PortRectbottom=PEEK WORD CWMgrPor t&+ 12) 

Por tRectright=PEEK WORDCWMgrPor t&+ 14) 

WINDOW 1,"TEdit Tour’, (PortRect lef t+4,PortRecttop+42)- 

— (Por tRectr ight-6, Por tRectbot tom-6),5 
X ТТІ; 
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EDIT FIELD 1,defaulttext$, C4, 4)-CWINDOW(2)-16, 
WINDOW(3)/2), 2 
SCROLL BUTTON 1,0,0, 10, 10, CWINDOW(2)-16,3)- 
CWINDOW(2), WINDOWC(3)/2+1),0 

CALL MOVETOC4, CWINDOW(3)/2)+22) 

CALL DRAWSTRING( “Change Byte: ^) 

EDIT FIELD 2,,(90 CWINDOW(3)/2)+ 13)-( 105, 
CWINDOW(3)/25+25) 

EFHnd12&=TEHANDLE (2) 

CALL MOVETOC 111, CWINDOW(3)/29+22) 

CALL DRANSTRINGC^TO^) 

EDIT FIELD 3,,C140, CWINDOWC(3)/2)+13)-C 155, 
CWINDOW(3)/2)+25) 

EFHnd13&=TEHANDLE (3) 

BUTTON 3, 1, “Enter”, (178, CWINDOW(C3)/2)+11)-(240, 
CWINDOW(3)/2)+27) 

APPLE MENU “TEdit Tour” 

MENU 1,0, 1, "File" 

MENU 1,1, 1, "View Text Edit Record" 

MENU 1,2,0,*-" 

MENU 1,3, 1, ^Quit/Q^ 

EDIT MENU 2 

DEF FN teWordPeek$(n)-PEEK WORDCPEEK LONGCTEHANDLE( 122*n) 

DEF FN teLongPeek&(n)=PEEK LONGCPEEK LONGCTEHANDLE( 1220) 

EDIT FIELD 1:CurrentField=1 

ON DIALOG GOSUB ^"DialogEvent^ 

ON MENU GOSUB "MenuEvent^ 

FLUSHEVENTS 

MENU ON:DIALOG ON 

“Loop” 

GOSUB “Info” 

GOTO “Loop” 

MENU OFF :DIALOG OFF 

*DialogEvent^ 

D-DIALOGCO) 


GOSUB "ButtonEvent^ 
CASE 2 


'EditEvent 
CurrentF ield-DIALOGC2) 
E 3 


‘Inactive Window 

CASE 4 

'Closebox 

IF т THEN END 


ASE 
GOSUB “Refresh” 
АЕ 6 


' Return Key 

CurrentF ield=DIAL06(6) 

IF CurrentField« 1 THEN GOSUB "ButtonEvent^ 
1 


' Tab Key 

CurrentF ield-DIALOGCT) 

LONG IF CurrentFieldo3 
EDIT FIELD CurrentF ield*1 
CurrentField-CurrentF ield*1 

XELSE 

EDIT FIELD 1 

CurrentFieldz1 

IF 


CASE 


“ Zoomin not used 
9 


‘ Zoomout not used 
CASE 10 
' Shift tab 
CurrentF ield-DIALOGC 10) 
LONG IF CurrentField« 1 
EDIT FIELD CurrentField-1 
CurrentField=CurrentF ield-1 
XELSE 
EDIT FIELD 3 
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CurrentF ield=3 


' Clear key 
CurrentF ield=DIALOGC 11) 
CASE 12 
' Left Arrow 
CurrentF ield-DIALOG( 12) 
CASE 13 
* Right Arrow 
CurrentF ield-DIALOG( 13) 
CASE 14 
‘ Up Arrow 
CurrentF ield=DIALOGC 14) 
CASE 15 
' Down Arrow 
CurrentF ield=DIALOGC 15) 
CASE 16 
^ Keypress 
END SELECT 
RETURN 
“MenuEvent”’ 
MenuNumber=MENU(@) 
Menul tem=MENUC 1) 


SELECT MenuNumber 
CASE 255 
GOSUB "appleID^ 
CASE 1 


GOSUB "fileID^ 
CASE 2 


' Edit Menu 

END SELECT 

RETURN 

*eppleID^ 

IF CurrentFieldoÓ 1 THEN EDIT FIELD 1:CurrentFieldz1 

WINDOW 2, "^, CPortRectleft*10,PortRecttop*30)- 
CPortRectright-12, PortRectbottom- 12), -2 

TEXT 4,9,0,0 

MOUSE ON 

PRINT “Byte”;SPC(5);*TEHANDLE = “; TEHANDLEC 1) 

PRINT “0 DestRect^,FN teWordPeek%(0),FN teWordPeek&(2), 
FN teWordPeek$(4), FN teWordPeek£(6) 

PRINT “8 ViewRect^,FN teWordPeek%(8),FN teWordPeek%( 10), FN 
teWordPeek%( 12), FN teWordPeek$C 14) 

PRINT 416 SelRect^,FN teWordPeek$C162,FN teWordPeek&( 18), FN 
teWordPeek%(20),FN teWordPeek%(22) 

PRINT "24 LineHeight^,FN teWordPeek$(24) 

PRINT “26 FontAscent^,FN teWordPeek%(26) 

PRINT “28 SelPoint’,FN teWordPeek%(28), FN 
teWordPeek% (39) 

PRINT “32 SelStart’,FN teWordPeek%(32), , "Byte" 


PRINT “34 SelEnd’,FN teWordPeek%(34),,*68 recallines",FN 
teWordPeek%(68 ) 

PRINT 436 Active’,FN teWordPeek%(36),,°78 ClickStuff^,FN 
ќеногдРеек 70) 

PRINT “38 WordBreek^,FN teLongPeek&(382,,"72 CrOnly",FN 
teWordPeek%(72) 

PRINT “42 ClickLoop^,FN teLongPeek&(425,,"74 txFont^,FN 
teWordPeek2C74) 

PRINT *46 ClickTime^,FN teLongPeek&(462,,"76 txFace’,FN 
teWordPeek%(76) 

PRINT “50 ClickLoc’,FN ќеногарРеек (50), , “78 txMode” FN 
teWordPeek%(78 ) 

PRINT “52 Cerettime^,FN teLongPeek&(525,,"80 txSize”,FN 
teWordPeek% (80) 

PRINT “56 CaretState",FN teWordPeek$(562,,"82 GrafPtr’,FN 
teLongPeek&(82) 

PRINT “58 Just",FN teWordPeek$(582,,"86 HighHook’,FN 
teLongPeek& (86 ) 

PRINT “60 teLength’,FN teWordPeek%(60),,°98 caretHook’,FN 
teLongPeek& (88 ) 

PRINT “62 hText^,FN teLongPeek&(622,,"94 nLines",FN 
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teWordPeek%(94) 

PRINT “66 RecalBack^,FN teWordPeek%(66),,796 LineStarts”, 
FN teWordPeek%(96) 

PRINT 

TEXT 2, 18 

PRINT РСС 15); “@MacTutor, 1987 

TEXT 2, 12 

PRINT SPC(30); "By Dave Kelly” 

PRINT SPC(27);*ZBasic Version 4.0" 

"Adis ON 


0 
mous-MOUSEC2) 
outsiderect-CMOUSEC 1) ‹0 OR MOUSEC1»WINDOWC2) OR 
MOUSEC22«0 OR MOUSEC2»»WINDOWC32) 
UNTIL mous? AND NOT Coutsiderect) 
MOUSE OFF 
WINDOW CLOSE 2 
TEXT 4,9,0,0 
GOSUB “Refresh” 
RETURN 
*fileID^ 
SELECT Menul tem 
CASE 1 
GOSUB “appleID’ 
CASE 3 


END 
END SELECT 
RETURN 
“Info” 
LONG IF CurrentField=1 AND WINDOW(O>=1 
TEXT 4,9,0,0 
PRINT 6С0, 17); "destRect:^,FN teWordPeekC0),FN 
teWordPeek(2), FN teWordPeek(4),FN teWordPeek(6) 
PRINT 60, 18); "viewRect:",FN teWordPeek(8),FN 
teWordPeekC 10), FN teWordPeek(12),FN teWordPeek( 14) 
PRINT 6(0, 19); "selPoint:^,FN teWordPeek(28),FN 
teWordPeek(38), 
PRINT @(0,20);“selStart:”,FN teWordPeek(32), “selEnd: ”,FN 
teWordPeek(34) 
PRINT @(8,22);*teLength:”,FN teWordPeek(60), "nLines: *;FN 
teWordPeek(94), ^hText^, PEEK LONGCFN teLongPeek&(62)) 
PRINT 6С0, 23); "txFont: ^, FN teWordPeek(74), 
*txFace:^; FN teWordPeek(76), *txSize:^,FN 
teWordPeekC80) 
END IF 
RETURN 
“Refresh” 
CALL TEXTFONT(4) 
CALL ТЕХТ517Е(9) 
CALL MOVETOC4, CWINDOW(3)/2)+22) 
CALL DRAWSTRING("Chaenge Byte: ^) 
CALL MOVETOC 111, CWINDOW(3)/2)+22) 
CALL DRAWSTRINGC^TO^) 
RETURN 
“ButtonEvent’ 
Byte$=EDIT$(2):NewByte$=EDIT$(3) 
FOR i= 1 TO LEN(Byte$) 
IF A La 1:«*0"^ OR MID$CByte$, i, 1>“9" THEN Byte$="" 
i 
FOR i-1 TO LEN(NesByte$) 
IF MID$(NewByte$, 1,12<70” OR MID$CNewByte$, i, 12» ^9"THEN 
NewByte$- *^ 
NEXT i 
IF Byte$-"" OR NewByte$-^" THEN В 
Byte&=VAL (Byte$) : NewByte&=VAL (NewByte$) 
‘Delete current text (BOMBS see discussion in MacTutor, Nov. 
87) 
‘ CALL TESETSELECT(O, 1090 , EFHnd13& ) 
‘ CALL TEDELETECEFHnd12&) 
‘ CALL TESETSELECT(O, 1000, EFHnd13&) 
‘ CALL TEDELETECEFHnd13&) 
EDIT FIELD 1:CurrentField=! 
POKE WORD PEEK LONGCTEHANDLE( 122*Byte&, МенВуіеф 
CALL SETRECTCDestRect$(0),FN teWordPeek(0),FN 
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teWordPeek(2),FN teWordPeek(4),FN teWordPeek(6)) 
CALL TEUPDATE(DestRect%(9), TEHANDLEC 122 
RETURN 


BASIC QUESTIONS AND ANSWERS 


Q. How can I determine the size of screen being used and 
draw my windows accordingly? 
A. Use the following lines of code (or similar) 


CALL GETWMGRPORT CWMgrPor t&) 

PortRecttop=PEEK WORDCWMgrPor t&+8) 

PortRectlef t=PEEK WORDCWMorPor t&+ 10) 

PortRectbottom=PEEK WORDCWMgrPor t&+ 12) 

PortRectright=PEEK WORDCWMgrPor t&+ 14) 

WINDOW 1,"TEdit Tour’, CPortRectleft*4, PortRecttop+42)- 
(PortRectright-6, PortRectbottom-6), 5 


Q. I’ve created a resource to be owned by my application, 
but I’m not quite sure how to go PEEKing and 
POKEing around with it. Could you explain? The 
resource 1S: 


PASS .Rsrc 

TYPE PASS=GNRL 
24 

1 

255 

‚1 

61 

‚Р 

DON’T PANIC! 


After compiling the resource the following program will 
open the resource file, move each resource to memory, 
PEEK and PRINT the contents, then change the resource 
by switching the integers and reversing the order of the 
string and rewriting the resource as the file closes. To use 
the resource with your application see my column in the 
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' Find out what application is named 
ResName$=F ILES$( 1, "^", , volg) 
IF ResName$-^" THEN END 
‘Open application resource file 
Refnum-FN OPENRESF ILECResNane$) 
Errnum=FN RESERROR 
LONG IF Errnuno 
ВЕЕР :PRINT“ERROR® *;Errnum 
PRINT “Problem with Resource File!” 
FOR i=1 TO 1000:КЕХТ i:END 
END IF 
CALL LOADRESOURCE(Refnum):’Load Resource into memory 
Rhnd1&=FN GETRESOURCE(CVIC“PASS”), 1) 
ResPtr&=USR3CRhnd1&): “Lock the handle and return a pointer 
firstint-PEEK WORDCResPtr&2:^ get the first integer 
secondint-PEEK WORDCResPtr&+2): ‘get the second integer 
FOR i=1 TO PEEK(ResPtr&*4) 
string$-str ing$  CHRÉCPEEKCResPtr&*4*i2) 
NEXT i 
PRINT firstint,secondint, str ing$ 
POKE WORD(ResPtr&),secondint: ‘save second into ist integer 
POKE WORD(ResPtr&+2),firstint:’ save first into 2nd integer 
POKECResP tr&+4), LEN(string$) 
FOR i=LEN(string$) TO 1 STEP -1 
Newstr ing$=Newstr ing$*MID$Cstring$, i, 1) 
i 


NEXT 
FOR 1=1 TO LEN(Newstring$) 
POKE(ResPtr&+4+i), CASCCMID$(Newstr ing$, i, 1222 


NEXT i 

CALL CHANGEDRESOURCECRhnd1& ) 
ResPtr&:USR7CRhnd1&2:^ Unlock the resource handle 
ce CLOSERESF ILECRef num) 


Thanks to Chas Stricklin of Shreveport, LA for asking the 
above questions. I'm sure there are other people out there th 
have some of the same questions. — 


См! 


fo “a “a = aN 
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Basic School 
Games for Teaching Children 


Happy 3rd Birthday MacTutor!!! I can hardly believe that 
MacTutor has been around for a whole 3 years. The Macintosh 
has certainly come a long way in that time. All the way from a 
puny 128K RAM model to the gobs of memory available for the 
Macintosh II. Let's celebrate! 

Every celebration should not be complete with out friends. 
First I thank all of you readers that have supported MacTutor 
these past years. But all of this would not be possible if not for 
the vision of one special, although fictitious character, Professor 
Mac. For those of you that have not met the Professor, turn to 
your front cover and take a look just in front of the big ‘M’ in 
MacTutor. The Professor started out teaching you Apple II 
Pascal in the "Apple Shoppe" (also published by David Smith). 
Since that time we've seen him popping in and out of the covers 
of MacTutor. (see Best of MacTutor Vol 1, pg. 1, 8, 13, 61, 71, 
92,107,313; Bestof MacTutor Vol2, pg. 2, 20,42, 357, 371-375; 
not to mention the numerous times the Professor appears at the 
end of each and every MacTutor column. 

A few days ago, the Professor reminded me that I haven't 
written any games lately. So whatshould the game do? Well, my 
oldest son, who was 3 (now аре 6) when we started up MacTutor, 
is now in first grade. Thanks to vol. 1 no. 1, Kevin now knows 
his ABC's. (see Bestof MacTutor Vol 1, pg. 298). I guess besides 
learning to read the next thing that first graders learn to do is 
count. So... a counting game!!! 

Last week Kevin brought home some homework that was just 
type of game I was looking for. The problems showed a price tag 
with a price. To solve the problem, he had to cut and paste 
pictures of coins under the price tag to equal the amount on the 
tag. So Professor Mac’s coin game was born. The object of the 
game is to click on the fewest possible number of coins to equal 
the amount of money shown in the price tag. If too many coins 
are selected the answer is not wrong, but the program lets you 
know that you could have done it with fewer coins. If you know 
that you have too many coins you may subtract coins by clicking 
the radio button named subtract and clicking on the coin you want 
toremove. The game does require some ability to read. Children 
that don’t know their numbers will have problems with this. At 
least it passed my kid test... Kevin loved it. 

On the technical side: the program doesn’t have any real 
surprizes technically. However, there are a few annoyances that 
appear to be ZBasic’s fault. In fact, sometimes I wish I was 
writing in Pascal or C. The blow by blow description follows: 

There are four PICT resources, a quarter, a dime, a nickel, 
and a penny, which are used. These resources should be installed 
in the application itself in order to work. Creation of the coins 
was done via Thunderscan® by clipping the scanned pictures 
into a resource file using ResEdit. The “Get Coin Resources” 
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Basic 


Dave Kelly 
MacTutor Editorial Board 
MacTutor Vol. 3 No. 12 


" é File Edit Ы 


Sa)? Professor Mac's Coin Game 


4 
ча 


K Add Coin 


O Subtract 


1 Quarters, 1 Dimes, O Nickels, 1 Pennies 
Total: $.36 


Fig. 1 Our coin game display 


subroutine gets the handles to the resources by using the ROM 
function GETNAMEDRESOURCE. Each resource is then 
loaded into memory (from the disk). Each coin is displayed on 
right side of the screen to give you something to click on to select 
the coins in the game. The ZBasic PICTURE statement will 
display the PICT resources by using the handle for the resource 
which was retrieved with GETNAMED RESOURCE. The 
active area to select each coin is marked by the Qrect, Drect, 
Nrectand Prectrectangles. Here is where the first problem shows 
up. The SETRECT call is used to set up the coordinates of each 
rectangle. But the SETRECT parameters are mixed up. Inside 
Macintosh shows SetRect parameters as being left, top, right, 
bottom in that order (see IM page I-174), but the ZBasic manual 
says the ZBasic parameters for SETRECT are Top, Left, Bottom, 
Right. The call (fortunately) works like IM; there is a typo in the 
ZBasic manual, pg. E-169. 

The event loop is established using menu, dialog and mouse 
events in the same way that has been demonstrated in other 
programs. There are a few funnies that show up though. Inearlier 
versions of the program, when I was still working on it, I used 
MOUSE ON, MOUSE OFF to control the About menu dialog. 
The problem was that when the About dialog was closed the 
screen erased itself just after the refresh routine did its refresh. 
This left a blank where the dialog window was. The screen had 
been updated, but something in ZBasic was trying to do its own 
refresh (I guess?). When I turned off all the event trapping for the 
About routine, the screen refreshed properly. This appears to be 
one of those little obscure bugs in ZBasic that nobody has fixed 
yet. This one problem turned what should have been a few 
minutes of programming into several hours trying to figure out 
what was going on. The GETMOUSE routine turned out to be 
just the solution. I get the feeling that I should be writing all my 
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code using the toolbox calls and leave the ZBasic routines to the 


cockroaches (or other “bugs’). 


‘Professor Mac’s Coin Game 
‘By Dave Kelly 

‘ @MacTutor, DEC. 1987 

‘ For ZBasic™ version 4.6 


WINDOW OFF 

COORDINATE WINDOW 

DEF MOUSE-- 1 

False=0:True=NOT False 

DIM Qrect%(3), Drect%(3), Nrect%(3), Prect%(3), 
playrect%(3) 

DIM 63 А$С4) 

Mousy=0: ’Set up point record 

Mousx=8:’for mouse location 

WINDOW 1,77 (2,22)-(510,3352,4 

CALL SETRECT(Qrect(8),388,0,510, 88) 

CALL БЕТРЕСТ(Огесі(02,388,81,510, 140) 

CALL SETRECT(Nrect(@),388, 141,510,215) 
CALL SETRECTCPrect(8),388, 216,518,319) 
CALL SETRECTCDisplayrect(8),8, 140, 385, 250) 
BUTTON 1,0, “Ада Coins”, (308,88)-(375, 1002,2 
BUTTON 2,0,"Subtract^, (300, 119)- (375, 130), 2 
APPLE MENU “About Professor Mac's Coins...” 
MENU 1,0, 1, File” 

MENU 1, 1, 1, Мен Amount /N^ 

MENU 1,2,1,"Quit/Q^ 

EDIT MENU 2 

Amount! 

GOSUB “Get Coin Resources” 

GOSUB “Draw Page" 

ON MENU GOSUB “MenuEvent’ 

ON DIALOG GOSUB “DialogEvent’” 

ON MOUSE GOSUB "MouseEvent^ 

MENU ON:DIALOG ON:MOUSE ON 


DO 
UNTIL TheEnd 
acd OFF:DIALOG OFF:MOUSE OFF 


*MenuEvent ^ 
Menunumber-MENUCE) 
Menuitem-MENUC 1) 
MENU 
SELECT Menunumber 
CASE 255 
60508 "AppleMenu^ 
60508 “Display Amount” 
GOSUB “Draw Page” 
CASE 1 
GOSUB "FileMenu"^ 
CASE 2 
END SELECT 
RETURN 


*AppleMenu^ 

WINDOW 2,^"^,C100,402- (415,310), -2 

TEXT 0,12 

PRINT 6С5, D^Professor Mac’s Coin Game” 

PRINT €C 10,2)”by” 

PRINT @(8,3)"Dave Kelly” 

PRINT @(7,4)*@MacTutor, 1987" 

PRINT @(7,5)*ZBasic version 4.0" 

PRINT @(3,8)*Professor Mac’s MacTutor Store will” 
PRINT @(3,9)*display prices on the price tag.” 
PRINT @C3, 10)*The object is to select (by clicking)” 
PRINT @(3,11)*the fewest number of coins to equal” 
PRINT @(3, 12)’the price. Hopefully this may be of” 
PRINT @(3, 13)^assistence to children first learning” 
PRINT @(3, 14)%about money." 

DO 


436 


CALL GETMOUSE(Mousy) 

outsiderect=(Mousx<@ OR Mousx?»300 OR Mousy<@ OR Mousy) 270) 
UNTIL FN BUTTON AND NOT Coutsiderect) 

WINDOW CLOSE 2 

RETURN 


*FileMenu^ 
SELECT Menuitem 
CASE 1 
GOSUB “Мен” 
CASE 2 
GOSUB “Quit” 
END SELECT 
RETURN 


*Quit^ 

‘Release all resource handles 
CALL RELEASERESOURCECQHnd1&) 
CALL RELEASERESOURCE CDHnd1& ) 
CALL RELEASERESOURCECNHnd1& ) 
CALL RELEASERESOURCE(PHnd1&) 
CALL RELEASERESOURCECTHnd1&) 
n RELEASERESOURCE (MHnd1&) 


“New” 

RANDOMIZE TIMER 
Amount = ВМО С 100 )* .01 
Add=True 

NumOf 03-0 

Мит0Ғ0%-0 

NumOf NZ=8 

NumOf P%=8 

Total !=8 

GOSUB “Display Amount” 
GOSUB “Display Total” 
GOSUB “Draw Display” 
BUTTON 1,2 

BUTTON 2, 1 

RETURN 


*DialogEvent^ 
Dilg-DIALOGCO) 
SELECT Dilg 
CASE 5 
Ref Win=DIALOG(5) 
‘Get window to refresh 
WINDOW 1 
GOSUB “Display Amount” 
GOSUB “Draw Page” 
CASE 1 
But tonpressed=D IAL06( 1) 
BUTTON Buttonpressed, 2 
LONG IF Buttonpressed=1 
BUTTON 2,1 
Add=True 
XELSE 
BUTTON 1,1 
Add=False 
END IF 
END SELECT 
RETURN 


“Display Amount” 
ТЕХТ 3,24, 1,8 
PICTURE (60,50), THnd1& 
CALL MOVETO (138, 100) 
PRINT USING ^$5.55^; Amount! ;SPC(2) 
RETURN 


“Display Total’ 
ТЕХТ 2, 12, 1,9 
CALL MOVETOC5, 285) 


PRINT Num0fQ;^ Quarters, *; NumOfD;” Dimes, “;  NumOfN; * 
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Nickels, “; NumOfP; ^ Pennies” 
CALL MOVETOC5, 300) 
PRINT “Total:”; USING “$3.95. Total! 
'Check for winner 
IF Total!=Amount! AND Total! 0 THEN GOSUB ^WinDialog" 


RETURN 


*WinDialog^ 
Temp !=Amount ! 
CorrectNum0fQ%=Temp! / . 25 
Tenp!sTemp!-CorrectNumOf Q%* . 25 
CorrectNumOf D$- Temp ! / . 1 
Temp !=Temp!-CorrectNumOfD&*. 1 
CorrectNumOf NS- Temp ! / . 05 
Temp!sTemp!-CorrectNumOf № . 05 
CorrectNumOf P$-Temp ! * 100 
LONG IF NumOfQ%=CorrectNumOfQ% AND Мит0Г0%- 
AND NumOfNZ= CorrectNumOfN% AND NumOfP%= CorrectNumOfPs 
A$C1)=*TA-DA! You Did it!” 
A$(2)=*Select ‘New Amount’ to start again’ 
A$C3)2^^ 
A$(4)="4 
CALL PARAMTEXTCA$C 1), A$C2), A$(3), А$С4)) 
Response%=FN ALERTC 1,0) 
XELSE 
A$C1=*Nice Try!” 
A$(2)=*You have too many coins!” 
A$(3)=“You should have: “+ STR$(CorrectNum0fQ%)+ ” Quar- 
ters, * *STR$(CorrectNumOfD2)* ~ Dimes,” 
A$C4)=STR$CCorrectNumOfNS)+” Nickels, «+ 
STR$C(CorrectNum0fP$)*^ Pennies” 
CALL PARAMTEXTCA$C 12,А%(22,А%(32,А%(402 
Response%=FN ALERT( 1,0) 
END IF 
Amount !=@ 
BUTTON 1,0 
BUTTON 2,0 
RETURN 


*TooMuchDialog^ 


A$C1)=*Adding that coin will give you “+ USING "$8,887; To- 


tal! 
А$(2)=°Тгу a different coin!” 
А$(3)=” * 
A$(4)=" * 
CALL PARAMTEXTCA$C12,A$C22,A$C32,A$C42 
Response$-FN А.ЕВТС1,02 
ETURN 


*No More Coins" 
A$C1)=*Sorry, You don’t have any more **Coin$ 
A$(2?2* * 
A$(3)=" * 
А$(4)=” * 
CALL PARAMTEXTCA$C 1), A$C2),A$C3),A$C4)) 
ResponseZ=FN ALERT(C1,0) 

RETURN 


“Get Coin Resources” 
QHndl&-FN GETNAMEDRESOURCEC — CVIC^PICT^), “Quarter”) 
CALL LOADRESOURCE CQHnd1& ) 
DHndl&-FN GETNAMEDRESOURCEC — CVIC^PICT^), іле”) 
CALL LOADRESQURCE CDHnd1& ) 
NHndl&-FN GETNAMEDRESOURCEC — CVIC^PICT^), ^Nickel^) 
CALL LOADRESOURCE CNHnd1& ) 
PHndl&-FN GETNAMEDRESOURCEC — CVIC^PICT^), "Penny^) 
CALL. LOADRESOURCE(PHnd1&) 
THndl&-FN GETNAMEDRESOURCEC CVIC*PICT”), “Tag”) 
CALL LOADRESOURCECTHnd1&) 
MHndl&-FN GETNAMEDRESOURCEC — CVIC^PICT^), “Professor 

c^) 


M 
CALL LOADRESOURCE(MHnd1&) 
RETURN 
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*Drew Раде” 
PICTURE (400,0),QHnd1& 
PICTURE (406,78), DHnd1& 
PICTURE (400, 138),NHnd1& 
PICTURE (406,220),PHnd1& 
CALL MOVETO(CS385,0) 
CALL PENSIZE(2,2) 
CALL LINETO(C385,340) 
CALL MOVETOC6, 135) 
CALL LINETO(385, 135) 
CALL PENNORMAL 
PICTURE (9,0),MHnd1& 
CALL MOVETOCOO, 40) 
TEXT 2, 18,0,0 
PRINT "Professor Mac’s Coin Game” 
“Draw Display” 
CALL ERASERECT(Displayrect(8)) 
IF Мип07090 THEN PICTURE (@, 140), QHnd1& 
IF NumOfD>@ THEN PICTURE C100, 140), DHnd1& 
IF NumOfN>® THEN PICTURE (290, 140), NHnd1& 
gue ы. THEN PICTURE (300, 140),PHnd1& 


*MouseEvent ^ 
IF Amount!=8 THEN FLUSHEVENTS : RETURN 
CALL GETMOUSE(Mousy) 
LONG IF (FN PTINRECT(Mousy, Qrect£(0))) 
LONG IF Add=True 
Total !=Total!+.25 
Num0fQ=NumOfQ+1 
GOSUB “Draw Display” 
XELSE 
LONG IF NunmOfQ- 1«0 
Coin$="Quar ters!” 
GOSUB “No More Coins” 
XELSE 
NumOf Q-NumOf Q- 1 
Total !=Total!-.25 
IF Total!<® THEN Total!sTotal!*.25 
GOSUB "Drew Display’ 
END IF 
END IF 
LONG IF Total!»Amount! 
GOSUB “TooMuchDialog’” 
Total !=Total !-.25 
NumOfQ=Num0fQ- 1 


END IF 
GOSUB “Display Total” 
END IF 
LONG IF FN PTINRECT(Mousy,Drect(0)) 
LONG IF Add=True 
Total!=Total!+.1 
Num0fD=Num0fD+ 1 
GOSUB “Draw Display" 
XELSE 
LONG IF NumOfD- 1«0 
Coin$s^Dimes!^ 
GOSUB "No More Coins” 
XELSE 
Num0fD=Num0fD- 1 
Total !=Total!-.1 
IF Total!<@ THEN Total!=Total!+. 1 
GOSUB “Draw Display” 
END IF 
END IF 
LONG IF Tota!!»Amount! 
GOSUB "TooMuchDialog^ 
Total!=Total!-.1 
NumOfD=NumOfD- 1 
END IF 
GOSUB “Display Total” 


END IF 
LONG IF FN PTINRECT(Mousy,Nrect(@)) 
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LONG IF Add=True 
Total !=Total!+.05 
NumOf N=NumOfN+ 1 
GOSUB “Draw Display" 


ELSE 
LONG IF NumOfN-1<0 
Coin$s^Nickels!"^ 
GOSUB “No More Coins” 
XELSE 
NumOf NsNumOf N- 1 
Total !=Total !-.@5 
IF Total!<@ THEN Total !=Total!+.05 
GOSUB "Drew Display” 
END IF 
END IF 
LONG IF Total Amount! 
60508 “TooMuchDialog” 
Total !=Total!-.05 
NumOf N=NumOfN- 1 
END IF 
GOSUB “Display Total” 
END IF 
LONG IF FN PTINRECTCMousy, PrectC0)) 
LONG IF Add=True 
Total!sTota1!*.01 
NumOf PzNumOfP * 1 
GOSUB “Draw Display” 


ELSE 
LONG IF NumOfP- 1«0 
Coin$s^Pennies!^ 
GOSUB “No More Coins” 
XELSE 
NumOf P=Num0f P- 1 
Total !=Total!-.81 
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IF Total!<® THEN Total!=Total!+.8! 
GOSUB “Draw Display” 
END IF 
END IF 
LONG IF Total!>Amount! 
GOSUB “TooMuchDialog” 
Total!=Total!-.81 
NumOfP=NumOfP- 1 
END IF 
GOSUB “Display Total” 
END IF 
DO:UNTIL NOT (FN BUTTON) dl 
FLUSHEVENTS je, 
RETURN 


Professor Mac's Coin Game 
by 
Dave Kelly 
©MactTutor, 1987 
2Basic version 4.0 


Professor Mac's MacTutor Store will 
display prices on the price tag. 

The object is to select (by clicking) 
the fewest number of coins to equal 
the price. 
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Neon News 
HFS Grep & Scrollers in Neon 


HFS Tiny Grep Utility in NEON 2.0 

We'll have a NEON column again after a long pause; just 
recently I received a beta copy of NEON's version 2.0 (already 
mentioned in the last column). NEON 2.0 is the long-awaited 
HFS compatible upgrade, with a lot of changes in the file class 
definitions and the introduction of a new class, pathlist. With this 
class, HFS search paths may be defined which are then scanned 
by the NEON system when files are accessed. Usually, you setup 
the default search paths in a text file which is kept in the NEON 
folder and read automatically at startup. If you've set the path 
names to the appropriate disk and folder names that you are using 
in your particular development system, the HFS tree search along 
the path list becomes completely transparent. You may then, for 
all practical circumstances, regard the collection of folders 
defined by the search path names as one contiguous MFS 
volume. With one important difference: pathlist is a subclass of 
ordered-col, and new search paths may be added to or removed 
from the list by sending add: or remove:. This can occur during 
the execution of a program, so you may dynamically change 
search paths as your application requires. 

Applications written in NEON 2.0 can be installed as one 
single file, putting the kernel and the dictionary together (which 
were separate in earlier versions). Installed applications have 
access to the finder information block through anotherclass, Fin. 
Therefore we may determine how many documents were opened 
together with the application and whether they are supposed to be 
opened or printed. 

I'm not going to give you all the details on NEON 2.0; quite a 
number of bugs seem to have been removed, and all in all the 
system seems to be more stable than the earlier versions. Never- 
theless, the version that I saw is a beta test, therefore some bugs 
can still be expected. Which leads us to this month's example, a 
string search utility for text files that will work on HFS volumes. 
Itis very much like the NEON 'grep' utility, which only works for 
MFS, however (even in the 2.0 beta version). 

Grep, incidentally, means general regular expression parser, 
which neither the NEON grep nor our example really are. We are 
justlooking for simple strings in a setof files and cannotuse more 
complicated expressions to define a whole range of strings to 
look for, such as а тезі” grep can do. 

Anyway, a directory-search utility for HFS volumes with 
added string search in text files makes a good example for using 
HFS from within NEON, and might also be useful to replace the 
Grep module on the NEON system disk. Note that the program, 
given in listings 1 and 2, will not work with earlier versions since 
it contains some v2.0 specific words. 

Even though NEON 2.0 works well with HFS, the HFS - 
specific traps are not (yet?) directly supported. Therefore we 
create a simple HFS dispatcher word, HFSd, which takes a 


440 


Jórg Langowski 
MacTutor Editorial Board 
Grenoble, France 
MacTutor Vol. 3 No.1 


ii é File Edit Utilities Neon" WirTool 


neon.Beta 


Macintosh NEON Version 2.0 
Bytes Available: 220815 


0-».. 
minLeadingZ 
mntLding2 
ModalDialog 


Monaco 
MoreMasters 


PROCEDURE ModalDialog € filterProc : ProcPtr ; VAR itemHit : 
Integer 2; TRAP $9991 
CIM 1-415 


(^ 


Sm 


ig. 1: Example of the WinTool Inside Macintosh data base 


parameter block address and a function code off the stack, passes 
them to the HFS dispatcher in registers AO and DO, calls the 
dispatcher trap and puts the result code from DO back on the 
stack. The function codes for the HFS-specific calls are given at 
the beginning of the listing. We use only openWD here, which 
given a path name in the parameter block, opens the correspond- 
ing working directory (folder) and returns a directory ID number 
in DO. 


Scanning a directory for files and folders 

There exists a NEON word, getidxfile, which can be used on 
MFS disks to get information about the i-th file in the directory. 
It calls the getF Info trap and places the information in the fFcb 
parameter block, which in turn can be used to open the file. HFS 
volumes, however, have to be treated differently. getFInfo still 
works sometimes on the root level of a volume, and also, by 
setting the appropriate volume ID, in folders; but it won't find 
subdirectories and, worst of all, sometimes crashes (at least 
according to some experiments I did both in NEON and Mach2). 
The correct way to scan an HFS directory is tocall the getCatInfo 
routine, which will return the i-th directory entry and also 
indicate whether it is a file or another folder. This is implemented 
in the getixHFSfile word (listing 1). 

Scanning through all of the disk now becomes very simple: we 
start with the root directory, and as soon as we find an entry that 
is another directory, we call the scanning routine recursively and 
repeat the process (remembering the old directory ID and file 
index on the stack). Scanning will be finished when no more 
entries are found in a directory; then the recursion will back up 
one level, until one is back at the root level and finished with all 
of the disk. 

The DIR routine implements this strategy of descending the 
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directory tree. It makes use of another definition, $openWD, 
which expects a string address as an input parameter, opens that 
particular folder and returns the directory ID (or an error code) on 
the stack. Successive calls to nextFile will return file or folder 
names further and further down the list of the working directory; 
if a folder is found, it is opened and a DIR done on its contents. 
Note that words may be called recursively in NEON, since no 
smudge bitis setduring a definition. If you wanted to rewrite DIR 
in Mach2, you would have to indicate explicitly that this is to be 
a recursive definition (besides doing all the other necessary 
changes...). 

grepDIR, then, isour text file string searcher. It works exactly 
the same way as DIR, except that after a text file has been found, 
itis opened and scanned for the search string. All files except text 
files are ignored. The string search routine is part of the NEON 
source code, therefore we won't print it here. Simply take the grep 
source file,copy thesearchfile definition outof itand paste it into 
the example text. I have not written the program as a NEON 
module, but this can easily be done and you can rebuild your 
system with the new grep utility. Included is a word grepOne 
which will scan a single file, and menu definitions to change disk 
drives and turn the printer on and off. 


Control handling in NEON - an alternate way 

NEON usually takes charge of tracking controls in a CtIWind 
automatically. As one of our readers, Phil Barnard, remarked in 
a letter (part of which I already quoted in my last column), this 
automatic tracking of controls sometimes can lead to a stack- 
heap collision (system error 28). NEONs default stack setting, 
3000, seems somewhat low anyway, since one does get ID=28 
bombs out of the blue even in other situations, such as when one 
changes repeatedly from the NEON window to a desk accessory 
like MockTerminal and back. Those situations can be avoided by 
re-installing the NEON kernel with а larger stack; I generally use 
32K without any problems. 

The second program example, listing 3 (by Phil Barnard), 
gives an explicit implementation of a vertical scroll bar class. It 
creates an example window on which this scroll bar is used. I 
quote from his letter: 

" The existing vertical scroll bar class appears to have prob- 
lems (even the demo scrolling bombs if not handled right), which 
seems to be caused by overflow of the return and methods stack 
during the repeated execution of the ‘Pascal’ procedure passed 
as a parameter to the TrackControl toolbox call. Am I right? 

This may be avoided by passing (-1) instead and only using the 
TrackControl call to track the thumb as in the following demo 
(...). To run the demo, load it and type the word ТЕЅТ'. After the 
demo, click in fWind and type ‘FIX’. " 

After my tests, this seems to be one other way to avoid stack 
crashing problems; it works with smaller stack sizes than the 
standard NEON controls. As a general remark, if you see strange 
things happening with some of the predefined words of any of the 
existing Forth or Forth-related systems, just try and redefine the 
offending part yourself. This is very easy in Forth since often the 
source code for large parts of the system is provided or can be 
easily decompiled. 
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WinTool - Inside Macintosh on line database 

We have quite an active scene of Macintosh developers here 
in Grenoble. As an example of what is being thought up on the 
other side of the Atlantic, I'd like to present to with a very nice 
utility that I was able to preview recently and that I'm already | 
heavily using. In fact, it opens up considerable space on my 
crammed desk, because I can leave the three volumes of IM on 
the shelves most of the time now. 

The program is called WinTool; it is a small data base imple- 
mented as a desk accessory. Although at present meant to provide 
you with an instant means of getting IM information, it could be 
used as a general data base by setting it up appropriately. 

Here's how it works: You install a desk accessory (quite a hefty 
one, takes 44K) which is used to access indexed data bases that 
you keep somewhere on your development disk. The copy that I 
looked at contained a Managers and a Toolbox database. (Those 
bases, by the way, also take up quite a bit of space, all in all, 
installing Wintools will add 300 K to your system.) When you 
call up a desk accessory, it'll add a new menu, from which you 
may select options such as opening and closing bases, or (most 
important) finding entries. See figure 1. 

So you don't remember the parameters to pass to ModalDia- 
log? Just select the appropriate entry, and the correct procedure 
call - with trap number and IM page reference - will come up 
almost instantly. Even on my two-floppy system. Much faster 
than browsing through Inside Macintosh. This is particularly 
useful (for Forth users) if you want to add a new glue routine to 
a trap that has not been provided in your standard system, want 
to know the exact location of a system global, the structure of a 
particular record, etc. etc. The managers database gives you some 
sort of an 'overview' of definitions contained in the individual 
sections of IM; the Toolbox database then gives the details of the 
definition. Words may be selected in a file that you're currently 
working on and then found in the data base with the menu option 
‘find selection’. You can also add to the existing entries as your 
disk space permits, e.g. if you've found some particular quirks 
about how a certain routine works, about bugs and so on. I'm 
going to create my own index for Forth words, because I can 
never remember all of them (working with too many different 
Forth systems). 

PS: As you read this, WinTool might be obtainable through 
MacTutor mail order. [Watch for it in an up-coming issue.-Ed] 


One last remark for our French readers 

Since we seem to have quite a large readership in Europe and 
especially in France by now, I think it is appropriate to make one 
short remark about connecting a modem to the Macintosh in 
France. [Other readers may now skip to the next article.] 

The Macintosh may be very easily connected to a standard 
Minitel by a three-wire connection. [For other readers, who are 
still with me: the Minitelisa videotext terminal containing a 1200 
baud modem that the French postal service provides free of 
charge for you. Of course, they charge you to use it.] 

The way to set up the connection is as follows: Geta 3-pin DIN 
plug that plugs into the interface socket of the Minitel. Make the 
following connections: 
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DIN plug Macintosh DB-9 Mac Plus mini-DIN 


1 (TTL input) 4 (TxD+) 6 (TxD+) 
2 (ground) 3 (ground) 4 (ground) 
З (TTL output) 8 (RxD+) 8 (RxD+) 


and off you go. (Try using one of the standard terminal 
programs on it). 

Last minute news: I just received a newsletter from Palo Alto 
Shipping that there is a new Mach2 upgrade on its way which 
contains an integrated debugger (finally reinstalled), integrated 
editor, automatic resource integration into tumkey applications, 


and more nice things. I'll keep you informed on it. 
Listing 1: 


Tiny Grep and Directory Descent utility 


V € J. Langowski / MacTutor, 1986 
\ written in NEON v. 2.0 


DECIMAL 
-35 CONSTANT nsvErr 
-43 CONSTANT fnfErr 


С no such volume error ) 
С file not found error ) 


HEX 

3F6 CONSTANT FSFCBLen \ ›@ if HFS is being used 

-1 CONSTANT MFS V 71 if MFS is running 

( this global variable is given for your information. ) 

C It is automatically checked by the NEON 2.0 word hfs? ) 


18 CONSTANT Dir/File \ bit 4 determines whether it is 
V а file or directory 


DECIMAL 


\ Routine selectors for HFS traps 
1 CONSTANT OpenwD 

2 CONSTANT CloseWD 

5 CONSTANT CatMove 

6 CONSTANT DirCreate 
7 CONSTANT GetWDInfo 
8 CONSTANT GetFCBInfo 
9 CONSTANT GetCatInfo 
10 CONSTANT SetCatInfo 
11 CONSTANT SetVolInfo 
16 CONSTANT LockRng 

17 CONSTANT UnlockRng 


V some more constants 
80 CONSTANT FileParamSize 
106 CONSTANT CatPeremSize 


\ offsets into parameter block 

12 CONSTANT ioCompletion С completion routine [long word] ) 

16 CONSTANT ioResult С result code returned here [word] ) 

18 CONSTANT ioNamePtr \ holds pointer to file name string 
V or pathname string [long word] 

22 CONSTANT ioVRefNum 

24 CONSTANT FioFRefNum C path reference number [word] ) 

26 CONSTANT FioFVersNum C usually zero [byte] ) 

28 CONSTANT FioFDirIndex С index [word] ) 

30 CONSTANT FioFlAttrib C file attributes byte [byte] ) 

31 CONSTANT FioFlVersNum С version number [byte] ) 

32 CONSTANT FioFlFndrInfo 

48 CONSTANT FioDirID 

48 CONSTANT FioFlNum 


9 value Index 
0 value VolRefNum 
0 value DirID 


: ?dup dup if dup then ; 
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V the HFS dispatcher... 
create hfsD 

рор00 

рорАб 

$ А260 м, 

ривһ00 

next, 


: $openWD ( name -- VRefNum / errcode 0 ) 
@ fFcb ioCompletion * ! 
name *base fFcb ioNemePtr + | 
8 fFcb FioFDirIndex * w! 
fFcb +base OpenWD hfsD extend 
?dup if Ø else fFcb ioVRefNum + мё then; 


: getixHFSf ile ( indx X ResCode -- errorResCode ) 
\ setup parameter 
block: 
VolRefNum fFcb ioVRefNum + W! 
DirID fFcb FioDirID * ! 
pad *base fFcb ioNamePtr + ! \ expect file name here 
indx fFcb FioFDirIndex * W! \ pass current index 
hfs? IF fFcb +base GetCatInfo hfsD extend -> ResCode 
ELSE fFcb fcall PBGetFInfo extend -> ResCode 


V specify the volume 
\ pass directory id 


THEN 
ResCode \ pass ResCode on stack; 
: NextFile 1 ++) index index getixHFSFile ; 


@ value level 
: indent cr level 4 * spaces ; С for pretty printing 2 


: DIR (vol \ resCode -- } 

Ø -> Index ( initialize index ) 

vol -> VolRefNum € choose volume in internal drive ) 

2 -> DirID € specify root directory, significant in HFS ) 

BEGIN 

NextFile -» resCode 

ResCode 0- 

IF 

indent 
ffcb FioFlAttrib + Се С get the attributes byte ) 


Dir/File AND ( file or directory ? ) 
IF indent 

33 tface ." Directory -> " pad count type 

0 tface 

1 ++) level 


index volrefnum С push on stack 2 
pad $openwd DIR € recursive call to DIR ) 
-) volrefnum -> index С pop off stack ) 
-1 ++) level 
indent 
ELSE pad count type 
THEN 
THEN 
ResCode 
UNTIL € error found ) 


ResCode ( which error ? ) 
CASE 
fnfErr OF 
level ?dup 
IF cr 1- 4 * spaces 
33 tface ." End of directory" 0 tface 
ELSE cr 33 tface ." End of contents listing" 
0 tfece quit 
THEN 
ENDOF 
nsvErr 
. ENDOF 
cr ." Error 8" ResCode . 
ENDCASE 


OF cr ." There is no disk in drive number " vol 
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3 cr ." Error 8" ResCode . 
ENDCASE 
String gpattern remove: loadfile 
String linBuf : 
String terget 
0 value drive 
0 value "lines XV total lines searched 
: grepone 


\ SEARCHFILE - This routine searches а file for the presence of new: loadFile 
V gpattern, outputting all lines that contain the string. txtype 1 stdget: topfile 
V It is contained in the 'grep' source f ile on the NEON 2.0 disk. = IF 
\ Please insert the appropriate source code here.... " Enter search string:" doInDlg 
\ wá IF new: gpattern new: terget 
\ str255 -base count put: gPattern 
\ cls grepinit 
Openreadonly: topfile ?error 132 

: grepInit searchf ile 

0 -> "lines remove: loadFile 

indent ." Searching for: " print: gPattern CR THEN 

uc: gPattern 2drop THEN 

new: linBuf s 
7 

: grepd 0 -> level 

: grepDIR ( vol addr len V resCode gcurs --  ) drive " Enter search string:" 

new: loadFile new: gpattern new: target doInDlg if cls grepdir else drop then 

addr len str255 -base count put: gPattern Р 

curs -? gcurs -curs \ Preserve cursor status 

grepInit 1 menu f ilemenu 

0 -> Index V initialize index 3 menu editmenu 

vol -? VolRefNum \ choose volume in internal drive 7 menu grepmenu 


2 -> DirID \ specify root directory , immaterial for MFS 
: drivel 1-» drive 5 uncheck: grepmenu 4 check: grepmenu ; 


BEGIN ?peuse : drive2 2 -> drive 4 uncheck: grepmenu 5 check: grepmenu ; 
NextFile -» resCode : pron *print 7 uncheck: grepmenu 6 check: grepmenu ; 
ResCode 0- : proff -print 6 uncheck: grepmenu 7 check: grepmenu ; 
IF 

indent : init 
fFcb FioFlAttrib + C@ \ get the attributes byte " grepmenu. txt" getntxt 
Dir/File AND \ file or directory? drivel proff 
IF indent р 
33 tfece ." Directory -> " pad count type 
0 tface Listing 2: 'grepmenu.txt' Menu Text file for Listing 1 
1 ++) level 
index volrefnum \ push on stack APPLEMEN 1 
pad $openwd addr .len grepDIR "$14" 
Y recursive call to grepDIR "About Neon". .." about 
-> volrefnum -> index V pop off stack е NUL 
-] ++) level "RES" DRVR \ get desk accy names 
indent "\\\" 
ELSE pad count type fileMENU 256 
pad count name: topFile "File" 
volrefnum setVref: topfile "Quit" bye 
openReedOnly: topFile ?error 132 “\\\" 
GetFileInfo: topFile drop editMENU 261 
GetType: topFile txType = "Edit" 
IF searchf ile THEN "€Cut/X" null 
close: topFile drop "ССору/С" null 
THEN "(Paste/V" null 
THEN ZU 
ResCode \ go until error found grepMENU 262 
UNTIL "бгер" 
"бгер one" grepone 

ResCode Wr oss null 

CASE "бгер all" grepd 
fnfErr OF "Drive 1" drivel 

level ?dup "Drive 2" drive2 

IF cr 1- 4 * spaces “Printer on" pron 

33 tface ." End of directory" 0 tface "Printer off" proff 
ELSE cr 33 tface ." End of contents listing" "\\\" 
0 tface gcurs -> curs remove: loadfile quit XXX 

THEN 

ENDOF Listing 3: Example for directly accessed scroll bars in 
nsvErr OF NEON 

cr ." There is no disk in drive number " vol . ENDOF \ by Phil Barnard, Launceston, Tasmania, Australia. 
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\ 
\ actFW added since it is no longer contained in NEON 2.0 
V CJ. Langowski ) 
: actFW enable: menubar 
4 1 do i enable: filemen loop 
decimal initFont 


0 value part! 
:CLASS vsBar «super object 


rect vsRect 
ver wPtr 
Handle ctlHndl 


V initializes the scrollbar rectangle from the port rectangle 
“М PUTRECT: C wPtr -- 2 

put: wPtr 

getRect: [ get: wPtr ] 

2swap swap drop 

3 pick 16 - 

swap 2swap 

put: vsRect 
М 


V instantiates vertical scrollbar in window, returning handle іп 
ctlHnd1 
:М NEW: € -- ) 

0 \ room for ctlHandle returned 

get: wPtr +раѕе\ window pointer 


abs: vsRect \ scrollbar bounds rectangle 
nul l0Sstr V null Str255 

256 makeint \ visible 

0 makeint \ value 

0 makeint \ min 

0 makeint \ max 

16 makeint \ procID for scrollbars 

0 \ ref Con 


call NewControl 
put: ctlHnd1 
‚М 


\ disposes of heap storage for the scrollbars 
:M KILL: € -- 2 get: ctlHnd] call DisposControl ‚М 


\ draws scrollbars on update events 
:M DRAW: € -- 2 get: wPtr +base call DrewControls ;М 


V hilites the given part number 
:M HILITE: ( thePart -- } 
get: ctlHnd] thePart makeint call HiliteControl ;M 


"М РОТМІМ: € min -- 2 
get: ctlHndl swap makeint call SetMinCt] ;М 
:M GETMIN: С -- min ) 
word? get: ctlHndl call GetMinCt] IL ;М 
:M PUTMAX: С mex — ) 
get: ctlHndl swap makeint call SetMaxCt] ;M 
:M GETMAX: С -- mex 2 
word’ get: ctlHndl call GetMaxCtl IL ;М 
"М PUTVAL: € val -- 2 
get: ctlHndl swap makeint call SetCtlVal ‚М 
:M GETVAL: C -- val 2 


word? get: ctlHndl call GetCtlVal IL ‚М 


V tests to see which part got hit and returns 0 or partcode in part? 
"М TEST: € 77 2 
wordg get: ctlHndl where: fevent 6-1 
call TestControl I—L -> pert? 
‚М 
д 


\ tracks the mouse, executing pert handler's default procedure 
while mousedown 
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:M. TRACK: 
words 
get: ctlHndl 
where: fevent GL \ mouse point in local coordinates 


( -- partNumber or 0 on mouse-up ) 
\ space for INT result 


call TrackControl 


I->L 
‚М 
;CLASS 
window edWind 
vsBar edBar 


\ close activate draw content handlers 
: fix < 4 D 'cfas null actFW cr null actions: fwind 
close: edWind cls ; 


: ok? depth . depth Ø > if . then rdepth . mdepth . ; 
\ def ine scrollbar handlers 

: ShowValue 100 50 gotoxy getVal: edBer . ; 

: PUp getVal: edBar 5 - putVal: edBar showValue 
: POn getVal: edBar 5 + putVal: edBar showValue 
: Шр getVal: edBar 1 - putVal: edBer showValue 
(Оп getVal: edBer 1 + putVal: edBar showValue 
: doThumb track: edBar drop showValue ; 


we We % "e 


: doPart С pert? -- ) 

case 20 of LUp endof 
21 of LDn endof 
22 of PUp endof 
23 of PDn endof 
129 of doThumb endof 
drop 

endcese 


: mekeEd false setDrag: EdWind 
false setGrow: EdWind 
2 241 518 340 put: tempRect 
tempRect " ed" Ø true false new: EdWind; 


: drewAll draw: EdBar ; 


: contEd 

test: EdBar 

parts 

if part8 hilite: edBar 
begin stilldown? while 
pert? doPart 
repeat 

9 hilite: edBar 
then; 


: ectF become actFW cis ; 


: actEd begin 
next: fevent 
if 2drop then 
again; 

\ close activate draw content 

\ instantiate both windows & bar and display bar 

: test mekeEd 
set: EdWind 
addr: edWind 


-curs 
putRect: edBer 
\ setup vsRect from owning window 
new: edBar 
0 putMin: edBar 100 putMax: edBar 
Ø putVal: edBardraw: edBar 
«(4 D 'cfes null ectEd drawAll contEd actions: edWind 
‹[ 4 D ‘cfas null actF null null actions: fWind ; 


sel 


(5747474 eN 
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OOPS in Forth 


Object Oriented Programming for MacForth 


OOPS. 
They're getting to be all the rage. 


The Macintosh design was based on one. There are several 
available for a wide variety of hardware. Some are OOPS 
through and through, others are just OO extensions to existing 
languages. 

Welcome to OOPS, the column dedicated to Object- 
Oriented Programming Systems for the Macintosh . 

Its hoped this column will evolve into a comprehensive 
look at object-oriented programming on the Macintosh. For now 
I will focus my efforts on two languages, one of which has had 
a vast impact on people's understanding of object-oriented pro- 
gramming and supports a tool that makes standard Mac user- 
interface support much easier. The other is only of interest to die- 
hard FORTH programming freaks like myself. 

The first language is Object Pascal, and the second can be 
either Neon or ForthTalk. ForthTalk is anew product which I just 
received, and I already like it much more than I like Neon. We'll 
get into Object Pascal, either TML or MPW, next time. 

ForthTalk 


ForthTalk is a $55 extension to the MacFORTH program- 
ming language that adds capabilities to the system generally 
described as "flavors," a term I believe, if memory serves 
correctly, was borrowed from Common Lisp. (Incidentally, one 
of my pet peeves is that even object-oriented programmers don't 
seem able to agree on a standard terminology to describe their 
system's capabilities. I want to know exactly what is wrong with 
Smalltalk's terminology of Classes, Subclasses, Superclasses, 
Instances, and Methods. One answer, that few object-oriented 
languages offer multiple inheritance, and "flavors" provides an 
intuitive framework in which to discuss that capability, will be 
discussed in a moment). 

ForthTalk is distributed on two disks. The first disk contains 
the tools to create the ForthTalk Kernel. These include the 
"Token Resizer" (for expanding the number of definitions that 
MacFORTH can handle) and the "Forth Talk Loader", along with 
a slightly reworked copy of the "FORTH Blocks" file and a copy 
of the standard MacFORTH block file editor. The second disk is 
the library disk. Itcontains the source code to the "Vanilla" flavor 
(analogous to Smalltalk's "Object" class) plus a few more useful 
flavors, source code to the tutorial in "Chapter 1," plus source 
code files to a couple of demos that aren't described step-by-step 
within the documentation. 

ForthTalk is an extension to the current version of the 
MacFORTH kernel (which, as of this writing, is K2.4). This 
means you must be a licensee of MacFORTH K2.4 from CSI in 


© The Essential MacTutor, Vol. 3 


Paul Snively 
Contributing Editor 
ICOM Simulations, Inc. 
MacTutor Vol. 3 No.2 


order for ForthTalk to be of any use. Unfortunately Forth Talk 
does not appear to work with the Level 3 "Developer's version" 
of MacFORTH; working only with Level 2. Support is planned 
for CSI's new MacFORTH PLUS kernel. 

Getting ForthTalk up and running is very simple. The 
author, Steve Lindner, apparently decided that MacFORTH's 
default limit of 500 tokens per program was not enough, so he 
provided a utility that allows MacFORTH programmers to use 
more tokens, the recommended number being 2000. This appli- 
cation is executed first to make room for the extensions, leaving 
some for user-written programs. 

The ForthTalk Loader is then executed. This interesting 
piece of code is essentially a customized version of CST's vocabu- 
lary librarian, which is included with the Level 2 MacFORTH 
system. Written by Ward McFarland, the FORTH code grabs the 
precompiled extensions from a couple of resources in the re- 
source fork, neatly sidestepping the issue of how to distribute 
ForthTalk without distributing either the MacFORTH kernel or 
the source code to ForthTalk, which might prove damaging to 
InSite Computing. The ForthTalk Loader, having read in the 
extensions and attached them to the MacFORTH kernel, snap- 
shots the kernel so that the extensions are a permanent addition 
to the kernel. The system then returns to the Finder. 

That's all it takes to make a ForthTalk system. The remain- 
ing magic lies in the "Vanilla" file. 

Vanilla contains the definitions of several useful flavors. 
The most obvious of these is Vanilla itself, the root flavor. Every 
other flavor is a subflavor of Vanilla. (Almost every other flavor. 
The exceptions are called mixins, and Ill get to them in a minute). 

You're probably wondering "If this is the root flavor, why 
doesn't it get snapshotted into the kernel along with the flavor 
defining words?" Thereason why is one of the few shortcomings 
of an otherwise fine system. In the current version of ForthTalk, 
flavors cannot be correctly snapshotted because they, or more 
accurately, their instances, exist as entities in the application 
heap, not in the FORTH dictionary. Furthermore, in many cases, 
the instance may point to an instance of another flavor, etc. 
Ultimately a snapshot utility will be written to deal with these 
unique requirements. 

Having created the ForthTalk kernel, how is it used? The 
easiest thing to do first is simply double-click on the "Vanilla" 
file from the Finder. This will launch the ForthTalk kernel, load 
the "FORTH Blocks" file, and in turn the editor, and ultimately 
the "Vanilla" file. 

You are now in a powerful object-oriented FORTH envi- 
ronment. The best thing to do now is to read Chapter One of the 
documentation. Itisa simple, fun tutorial which, although simple 
in nature and objectives, covers everything from defining new 
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flavors and methods to the important concept which sets this 
System apart from all others I have used: multiple inheritance. 

A really basic data structure is always nice. So let's define 
an array, like this: 


FLAVOR Array Vanilla | 


Note: in ForthTalk, uppercase and lowercase are distinct. 
Make sure you case things consistently. In general, Forth Talk 
uses the convention that all uppercase words are "built-in" to the 
system, whereas mixed-case words were defined outside the 
kernel. 

What have we done with the above line? We have created 
a new flavor called Array. It has Vanilla as a superflavor. The 
vertical line indicates that we are done defining the new flavor. 
Experience OOPS users are probably scratching their heads, 
wondering why you must explicitly tell the compiler when you 
are finished defining a new flavor. The answer is that with 
multiple inheritance, you can have more than one superflavor. 

We've now defined a flavor called Array. What does it do? 
Nothing at this point. We need to tell it what kind of data 
structures and what kind of code make up an Array. 

The tutorial opts to keep things simple and use a fixed- 
length array. In order not to distract from our discussion of 
object-oriented programming, I will do the same. 

Let's make arrays to be big enough to contain ten longword 
(32-bit) values. We'll also need a way to keep track of how many 
of those ten elements are occupied. 

Most OOPS call the data structures within their classes (or 
flavors, in ForthTalk) "instance variables" because they are 
unique for all instances of that class. ForthTalk is really no 
different, but it is different from most OOPS in not using 
instances of other flavors as instance variables. Instead it relies 
оп "INST.XXXX" words (CINST.LONG," "INST. WORD," and 
"INST.SPACE") to create instance variables. So we can give 
Array its data structures like this: 


INST.LONG Array Count 
40 INST.SPACE Array Space 


We have just allocated a total of 44 bytes (40 bytes plus a 
longword) to Array. 4 bytes can be referred to as "Count" in the 
methods that we write for arrays, and the remaining 40 are 
referred to as "Space." 

Believe it or not, we have now given the flavor "Array" 
enough to work with in order to create arrays! We can create an 
object whose flavor is "Array" like this: 


Array CONSTANT MyArray 


As you can see from this example, flavors are fairly intelli- 
gent FORTH words. When youexecutea flavor, it figures out the 
total amount of space that it must allocate (44 bytes in Array's 
case), and allocates a block of that size in the heap. NOTE: 
flavors return a HANDLE to their data! 

Since flavors return a handle, we can simply use the normal 
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FORTH word CONSTANT to assign a name to the handle. 

We now have a new flavor that we've created, and we've 
used it to create an instance of itself, which we've named 
MyArray. What can we do with MyArray? 

At this moment MyArray is doing nothing but taking up 
space. What we need are methods for operating on the data in 
MyArray, and on any other arrays that we create. 

One obvious thing to do would be to store things in our 
array. We wantto create a method to do this, so let's callours :Set. 
In ForthTalk, all methods begin with a colon (":"), which the 
documentation says is a convention used by Smalltalk. I beg to 
differ with the documentation on this point; in Smalltalk, 
methods end with a colon. For the sake of internal consistency 
I have chosen to use the ForthTalk convention. 

The definition of :Set looks like this: 


METHOD Array :Set (х n ---) 
4* Space + ! ;M 


This method takes two operands on the stack. The value to 
store is first, and the element within the array is on the top of the 
stack. 

The method first multiplies the array index by four since 
each entry is four bytes long. It adds the result to Space (which 
refers to the firstbyte of the array). Theresultis the address where 
we wish to store our value, and the normal FORTH word ! does 
the job. 

Methods, like the instance variables that they manipulate, 
are buried somewhere within the flavor for which they are 
defined. Since that is the case, we need a way to make it possible 
to access them. This is done with the word DEFMESSAGE. It 
is used like this: 


DEFMESSAGE :Set 


This adds the word :Set to the FORTH vocabulary. When- 
ever this word is executed, it will look in the superflavor chain for 
the object whose address is on the top of the stack for a method 
called ":Set". If it finds one, it will execute it, otherwise it will 
print an error message. 

This raises two of the negative issues regarding ForthTalk. 
One is that messages must be defined externally with DEFMES- 
SAGE before they may be used. This problem is not present in 
any other OOPS that I know of including Neon. The other is that 
with multiple inheritance, there is a definite performance impact 
on method lookups. Both these issues are expected to be 
addressed in a future release of ForthTalk, probably the one that 
runs under the new MacFORTH PLUS kernel. 

We can use :Set to give values to our array, like this: 


3 0 MyArray :Set 


This will assign the value of three to the zeroeth element of 
MyArray. 

And here we see the beauty of object-oriented program- 
ming. The Array flavor is totally modular: its data cannot be 
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accessed by anything other than its methods, and its methods 
cannot be accessed without following protocol, and are entirely 
self-contained, too! As long as we avoid code that is dependent 
upon Arrays having ten elements and avoid changing the inter- 
face to any of the methods, we are safe! (In reality we would 
probably make the Array flavor dynamically sized). We can 
write new methods for Array and fiddle around with its data 
Structures without fear of the impact on any other part of the 
program! You can see why OOPS are becoming so popular for 
large programming projects or projects where a large team of 
programmers must work together! 


‘Init Method 


In order for ForthTalk to be truly useful, there is one more 
concept that should be addressed: the :Init method. 

:Init methods are usually needed, if only to provide some 
default values/actions for the instance of the flavor in question. 
In the case of Array, it would be nice to initialize the array to some 
set of values. For that reason, we have: 


METHOD Array :Init (тп... m2 ті n --- instance) 
Count ! 
Count @ 0 DO I SELF :Set LOOP 
SELF ;M 


This method takes several values on the stack: first, a series 
of values to be assigned to the array elements, then the number 
of items there are to assign. The method first stores the number 
of elements in Count, and it then uses Count in a DO ... LOOP 
construct. 

The loop counts from 0 to Count - 1 and :Sets the elements 
of its SELF to the values on the stack. For example: 


543215 MyArray :init 


This raises another interesting point about OOPS: they 
allow the programmer to write methods that use methods from 
either the same flavor or from one of the superflavors to get the 
job done. In this case, :Init uses :Set (since we want :Init to SET 
the elements to the values on the stack). 

Like Smalltalk, ForthTalk allows the use of the pseudo- 
object SELF to refer to whatever object is currently executing a 
method. 

Isn't this fun? We can add more methods now. One thing 
that's useful with Arrays is the ability to perform some function 
on all of the values stored in them. We'll call this method 
:DoToAIl and take advantage of a fact of MacFORTH: we can 
execute any word by getting its token and saying EXECUTE. 
TOKEN.FOR is a MacFORTH word that returns the token value 
for a word. 

With that thought in mind, here's :DoToAIl: 


METHOD Array :DoToAll LOCALS| token | 


Count @ 0 DO | 4* Space + token 
EXECUTE LOOP ;M 
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Note that this method passes the address of the value to the 
token, not the value itself. Whatever word token is for needs to 
be "aware" of that fact. 

Also note that the MacFORTH local variable facility works 
just fine within methods. This makes iteasier to define what goes 
into methods and what processing the methods do. 

Before we forget, we'd better: 


DEFMESSAGE :DoToAIl 


We can do useful things with :DoToAll. One of them is to 
show the contents of the entire array. We can define: 


METHOD Array :Print 
TOKEN.FOR ? SELF :DoToAII ;M 


DEFMESSAGE :Print 


With :DoToAIl the definition of :Print becomes trivial. We 
can get the token value for ?, which is a standard FORTH word 
which gets the longword at the address on the stack and displays 
it using . (another standard FORTH word). Passing this token, 
along with SELF, to :DoToAIl prints the values of each defined 
element. What could be simpler? 

Its hoped that this somewhat drawn-out description of 
ForthTalk's capabilities is giving you some insights (no pun 
intended) into how this OOPS can make your life as a Macintosh 
programmer easier. 

The remainder of the tutorial chapter in the ForthTalk 
documentation continues to develop the ideas behind the Array 
flavor. Ultimately a subflavor of Array called ObjectArray is 
created. The point behind ObjectArray is that its elements hold 
not just arbitrary numerical values but handles to instances of 
other objects. 

This leads to some interesting concepts, such as creating a 
normal FORTH colon definition that passes a message to what- 
ever object is on the top of the stack (assuming that the object 
"knows" the message). Again, the example given uses :Print 
(since so many kinds of objects can respond in a meaningful way 
to a :Print message). So, you wind up with something like this: 


: Print @ DUP INSTANCE? IF :Print ELSE CR . THEN ; 


This word is almost ridiculously simple: given an address 
on the stack, it uses the word INSTANCE? to determine whether 
the address contains a handle to an object or not. If it does, the 
word assumes that the object understands the message :Print and 
uses it, otherwise the word simply prints the number, after 
printing a carriage return. - 

In conjunction with the ObjectArray mentioned above, this 
opens uparather exciting possibility: printing an ObjectArray by 
passing the :Print message to all of its elements. Like any robust 
OOPS, ForthTelk has inheritance, which means that ObjectAr- 
rays inherit the :DoToAll method from their superflavor (Ar- 
rays). Since that is the case, defining the :Print method for 
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ObjectArrays becomes very simple. It looks like this: 


METHOD ObjectArray :Print 
TOKEN.FOR Print SELF :DoToAll ;M 
AXE Print 


Note: the AXE is to remove the header for our Print word, 
since it exists only as a tool to be used within the :Print method 
for ObjectArrays. 

This simple method uses our smart word Print to send the 
:Print message to all of the objects in the ObjectArray. As long 
as the object is of a flavor that understands :Print the ObjectArray 
flavor will exhibit sensible behavior, otherwise Print will just 
print the value stored in the ObjectArray. If that happens, you 
know that you have a bug. 

The upshot of all of this is that with just a couple of flavors 
and a few methods, you have the capability to create pictures. In 
an OOPS, a picture can simply be an ObjectArray which contains 
graphics objects that understand the :Print message. As long as 
all of the objects understand :Print asking the ObjectArray to 
:Print itself will result in each object :Printing itself, with the total 
result being a picture at some point on the screen. 

At this point the tutorial becomes interesting. Here is some 
sample code. See if you can determine in what direction we're 
moving with it: 


FLAVOR Circle Vanilla | 
INST.WORD Circle X 
INST.WORD Circle Y 
INST.WORD Circle Radius 


METHOD Circle :Init ( X Y Radius --- SELF) 
Radius W! 
Y WI 
X WI SELF ;M 


METHOD Circle :Print ( --- ) 
X W@ Y W@ Radius W@ FRAME CIRCLE ;M 


FLAVOR Line Vanilla | 
INST.WORD Line X1 
INST.WORD Line Y1 
INST.WORD Line X2 
INST.WORD Line Y2 


METHOD Line :Init ( X1 Y1 X2 Y2 --- SELF) 
Y2 W! 
X2 WI 
Y1 W! 
X1 W! SELF ;M 


METHOD Line :Print ( --- ) 


X1 WQ Y1 W@ MOVE.TO 
X2 WQ Y? W@ DRAW.TO ;M 


Some ideas are probably glimmering by now. There's no 
point in reproducing the ForthTalk tutorial here in its entirety. 
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Instead, I will leave the reader with a few questions to get him/ 
her going. 

What happens if you rewrite the graphics methods so they 
do their drawing relative to where the pen is, rather than drawing 
at absolute locations? 

What we are shooting for is a flavor that, when instantiated, 
creates an object that, when sent a :Print message, prints itself 
wherever we told it to at the time of instantiation. 


The Whole Point 


If we can do that: make a flavor which contains instance 
variables X and Y, and a FLAV.LONG referring to an ObjectAr- 
ray which in turn contains :Printable objects that print relative to 
the current pen position (whew! This is getting deep), THEN we 
can perform small miracles. Why? Because thanks to the magic 
of multiple inheritance, we can animate these objects - and we 
can do so in such a way that the animation code can immediately 
be used for other flavors of objects. 

This is what this whole article has been leading up to. We 
are going to create a new flavor called simply Animation. We are 
assuming that we have this relative-drawing flavor (the example 
in the documentation defines the flavor Automobile, which uses 
the ObjectArray defined earlier to draw a stick-figure car relative 
to the current pen position). 

I said that flavor Animation would be general, and it will: it 
will allow animation of any object that understands the :Print 
message (so far all of ours do), and the :GetXY Addr message 
(which so far NONE of ours do). Adding the ability to get the 
addresses of X and Y from any flavor that has them, like 
Automobile, is trivial: 


DEFMESSAGE :GetXYAddr 
METHOD Automobile :GetXYAddr 
X Y;M 


As you may have noticed, one way that the tutorial has been 
making methods general is by providing them with some external 
word (such as Print) which sends messages to do the dirty work. 
Vectoring is also very big (and what is an ObjectArray but a 
means of sending the same message to a bunch of different 
objects)? We'll take advantage of an external word again with 
Animation, but first let's create this fascinating flavor: 


FLAVOR Animation | 

INST.WORD Animation MoveToWhere 
DEFMESSAGE :Animate 
DEFMESSAGE :SetAnimation 


The most obvious weird thing about Animation so far is that 
it does not have Vanilla as a superflavor. This fact makes 
Animation what is known as a mixin; it is intended to be a 
superflavor itself, since by itself it has virtually no functionality. 

It does understand two messages, though: :Animate and 
:SetAnimation. Let's see :Animate first, since it's the one that 
actually moves the Automobile: 
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METHOD Animation :Animate ( --- ) 
SELF :GetXYAddr LOCALS| Y X | 
SELF :Print 
BEGIN 

SELF :Print 
X Y MoveToWhere W@EXECUTE 
( must leave a flag) 
SELF :Print 
UNTIL ;M 


It seems easy - as it should. This method assumes basically 
two things: that the current pen mode is PATXOR, so that 
successive drawing operations of the same thing at the same 
place will alternate the appearance and disappearance of the 
object, and that MoveToWhere contains the token of a word 
which takes the addresses of the X and Y location of the object 
and returns a boolean indicating whether the animation is done 
(true) or not (false). 

That only leaves :SetAnimation, which is easy to define: 


METHOD Animation :SetAnimation ( token ---) 
( token arglist is { X Y --- flag} where 
X = address of picture's X coordinate 
Y = address of picture's Y coordinate 
flag = TRUE if animation loop should end, 
FALSE to continue) 
MoveToWhere W! ;M 


It's all comment except for the last line, which simply stores 
the token. 

Now we can define an animated Automobile. We'll call it 
flavor MovingAuto, like this: 


FLAVOR MovingAuto Automobile Animation | 


That's all that's needed to create an animated automobile, 
aside from creating an instance! To do that, we can just say: 


10 100 MovingAuto :Init CONSTANT CarToon 


Well, almost all! We still have to create the word that 
actually changes X and Y and returns a true or false flag, 
depending upon whether we are done or not: 


: MoveRight ( X\Y --- flag) 


DROP DUP WQ 84 OVER W! WQ 400 >; 
TOKEN.FOR MoveRight CarToon :SetAnimation 
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This simple word ignores the address of Y completely 
(DROP). It then adds eight to the value of X (move the picture 
eight pixels to the right). Finally, the word checks the value of 
X to see if it has gone higher than 400. 

The last line simply uses the :SetAnimation method to store 
the token for our animation word so that we can move our car. So 
to see the CarToon move to the right on the screen, just say: 


CarToon :Animate 


and watch it drive by! 

With a new flavor containing only two methods and a 
helpful FORTH word, we have animated an otherwise inanimate 
object (pun intended). 

I'll close with a couple of paragraphs from the ForthTalk 
manual: 

"(A)... useful idea would be to keep around a palette of 
motions and motion combinations. These would include things 
like Bounce, Stop, GoToZero, Orbit, ParabolicArc, etc. These 
could be interchangeably used for any of your other pictures." 

"For another idea to try, :GetXY Addr could return the 
addresses of *any* two parameters, like Radius and Color, or like 
Speed and ZoomFactor. Then the Animation flavor would vary 
these things instead of just screen position." 


Final comment: if MacFORTH is your bag, and you want 
object-oriented programming and want it to be intuitive to an old 
FORTH hacker, but you want it to be very powerful and easy to 
learn, then spend the $55 and get ForthTalk. You won't regret it. 

MacFORTH users will ultimately be able to get Mac- 
FORTH PLUS and the version of ForthTalk that runs with it. 

Inthe meantime, there are a growing number of people who 
have more or less permanently moved over to MACH 2, the 
excellent 83 standard FORTH development system from Palo 
Alto Shipping. I am in the process of trying to convince InSite 
Computing to port their outstanding effort over to the MACH 2 
environment. Palo Alto Shipping has expressed an interest, 
Steve Lindner has expressed his personal interest, and I'd be 
interested, both as a MACH 2 user and as (hopefully) the MACH 
2 version implementor. ГЇЇ keep you posted on any progress 
made in that area. 

ForthTalk is available from: 


InSite Computing 

Box 2949 

Ann Arbor, MI 48106 
(313) 994-3660 
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Threaded Languages 


Building Desk Accessories with Forth 


A template desk accessory in Mach2 


Any of our readers who has taken a close look at Mach2 code 
will have noticed that the output generated by the Forth compiler 
resembles very much that of 'classical' compiled languages like 
Pascal. Disassembly shows that much of the code is inline- 
generated machine code, and references to kernel routines are not 
too frequent. 

This is one of the strong points of Mach2; retaining most of 
the ease of programming and debugging with a Forth interpreter, 
you can not only generate stand-alone applications, but also 
things that are much more dependent on interacting directly with 
the operating system such as V BLtasks that run independently of 
a runtime Forth kernel (see my article in V2#6 ); one could also 
imagine to create INIT resources, MDEFs or WDEFs and... desk 
accessories. 

The problem with Forth code in general is that a 'stand- 
alone-application' generated by any Forth system available for 
the Macintosh contains - and is dependent on - at least part of the 
runtime Forth kernel. Whether the kernel contains the interpreter 
(as in MacForth) or the task of interpreting is taken over by the 
CPU itself in subroutine threaded code such as Mach2 - the 
standard I/O routines, window handling, controls, menus etc. all 
come in a pre-written package that will form part of the stand- 
alone application. To write something like a desk accessory in 
Forth, this would imply that the runtime package had to be part 
ofthe DA. This is (a) not very practical because space-consuming 
and (b) notan available option in any Forth for the Macintosh that 
I'm aware of. 

Nevertheless, Mach2 allows us to create a functioning desk 
accessory without too much effort and allows me to simultane- 
ously illustrate some principles of DA programming to you at the 
same time. 


DA strategy for implementation in Mach2 


How would we proceed to build a desk accessory using 
Mach2? The DA is a DRVR resource. We would have to create 
this resource in memory first, then write it out to a resource file. 
There are resource manager routines that allow us to do this; 
AddResource will add a new resource to the current resource file, 
given a handle to a data structure in memory, and UpdateResFile 
saves these changes to the resource file. So all we have to do is 
to create a data structure of the format of a desk accessory, get a 
handle to it and call AddResource with the type DRVR to create 
the new driver, then update the resource file. 

The general format of a desk accessory is known from 
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Mach2 DA 


é File Edit View Special 


Key down. 
Mouse down 
Mouse down 


Fig. 1 Our simple DA, written In Forth! 


Inside Macintosh. The first couple of bytes are a header contain- 
ing flags that tell the system whether the DA needs to be called 
periodically, and what type of calls it can respond to; a delay 
setting that determines the time between periodic actions; and 
event mask that determines what events the desk accessory will 
respond to; a menu ID (negative) if the DA has a menu associated 
with it; and offsets to the Open, Prime, Control, Status and Close 
routines. These latter offsets are measured from the beginning of 
the desk accessory to the beginning of each of the routines. The 
last portion of the header is a string containing the driver name. 

The remaining portion of the desk accessory may be execut- 
able code and can be written in Mach2 Forth if we make sure that 
references to kernel routines are avoided. Before we discuss the 
example (listing 1), however, let me briefly summarize what 
happens when a desk accessory is opened. 


Opening the desk accessory 


When the DA (or any driver) is opened for the first time, a 
device control entry is created by the system, a data structure 
which contains information about the driver; it is described in 
Inside Macintosh (II- 190). It will, for instance, contain the driver 
flags, the delay setting, the event mask and the menu ID from the 
desk accessory header. Also a window pointer to a window 
associated with the driver may be stored here or a handle to a 
memory block if the DA needs to store large amounts of data. 

When adriver routine (open, control, close, status, prime) is 
called, a pointer the driver's device control entry is passed in 
register А1. The other parameter, passed in А0, is a pointer to the 
parameter block of the call. For desk accessories, this parameter 
block is important for Control calls since we'll be able to tell from 
the parameter block what has happened that the desk accessory 
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has to respond to, such as menu selections, periodic actions, 
editing commands, etc. 


Glue routines 


Since the parameters to the driver routines are passed in 
registers, we'll have to write some assembler code to make them 
‘digestible’ for Forth, which is stack-oriented. Also, we'll save 
А0-А1 and restore them after the call; as IM mentions, no other 
registers have to be saved. One important thing to remember is 
that we have to setup a Forth stack before using any actual Forth 
code; we make Аб point to a data block sufficiently large (100 
bytesin theexample, but you may easily change this to have more 
stack space). 

The glue routines then in turn call the driver routines which 
have been written in Forth. The routines referenced in the DA 
header are the glue routines, of course. The final part of listing 1 
contains the stack setup, the glue routines, and the part that 
initializes the desk accessory header and writes the driver code to 
a resource file. 

Thecode written is contained between (ће 'markers' startDA 
and endDA. For adding the resource to the file, the word make- 
res is provided, which gets a handle to a data structure in memory 
and calls AddResource with the handle, the resource type (DR VR 
in our case) and a resource file ID as parameters. 


init-DA will initialize the desk accessory's header. This 
includes setting the driver flags, the driver name, an event mask, 
the delay time between periodic actions, and calculating and 
storing the offsets between the start of the DA and the beginning 
of the ‘glue’ routines. Also, the ID of the DA's own menu is stored 
in the header; we'll come back to that later. 


make-DA calls init-DA and then writes the newly created 
DRVR resource with ID=12 into the file "Mach2 БА тѕгс". This 
file can then be used by RMaker to create a Font-DA Mover 
compatible file that contains the DA and any resources owned by 
it. 


DA-owned resources 


Listing 2 shows the RMaker input file. It will include the 
DRVR code from "Mach2 DA гѕгс" and two more resources, a 
window template and a menu. Both these resources have an ID 
of -16000, which later indicates to the Fon/DA Mover that they 
are 'owned' by the desk accessory whose ID is 12; they will 
therefore be moved together with the DA. If the DA's ID is 
changed during the move, their IDs will be changed accordingly 
so that they always correspond to that of the DA. 

The format of the ID number of an owned resource is given 
in IM (1-109); I'll briefly review it here. The ID number is always 
negative and bits 15 and 14 are always 1. Bits 11-13 specify the 
owning resource type, andare zero fora DRVR. Bits 5-10 contain 
the ID number of the owning resource, which therefore must be 
between 0 and 63. Bits 0-4 may contain a number which identi- 


© The Essential MacTutor, Vol. 3 


fies the individual resource. Therefore, the allowed number 
range for owned resources is between -16384 and -1. 

If the DRVR resource has an ID=12, the IDs of the owned 
resources start with -16000 ( if bits 0-4 are zero) and go up to - 
15969 ( bits 0-4 = 31). Since -16000 is a simple number to 
remember, the DRVR is given an ID of 12 when it is created by 
the program. Both the MENU and WIND resources owned by the 
DRVR in the example will have IDs of -16000 (which corre- 
spond to 'local' IDs of 0). 

Two Forth words are provided to easily convert local IDs to 
ownedresource IDs. getDrvrID will calculate the driver ID from 
its reference number, which is kept in the device control entry; 
and ownResID will calculate the owned resource ID from the 
driver ID and the local resource ID. 


The desk accessory 


We can now take a look at the desk accessory's main code. 
The Open routine is called by the DAOpen glue routine. It will 
do nothing if the desk accessory's window is already open, which 
can be checked by looking at the dCtIWindow field in the device 
control entry. If the DA has not been opened yet, or has been 
opened and then closed again, it will create a new window from 
the WIND resource with local ID=0 and store its pointer in the 
device control entry; furthermore, it stores the driver reference 
number in the windowKind field of the window record. By this 
means, the desk manager will know thata window belongs to the 
DA, how to find it and to send the appropriate messages to the DA 
when the window is activated, deactivated, the mouse clicked in 
its content region or when it is closed. 

Open will in addition calculate the ID of the MENU 
resource (local ID=0) that is owned by the DA. This number is 
also stored in the DA header, but you cannot reliably assume that 
itis correct. Font/DA Mover will change the DA's ID and the IDs 
of its own resources correctly, but it doesn't go into the DA header 
and sets the correct menu ID. However, some negative menu ID 
has to be present in the DA header in order to tell the desk 
manager that the DA has to respond to menu selections. The 
device control entry, however, has to contain the correct menu 
ID; otherwise the DA won't respond to its own menu. 

Close will store zero in the dCtlWindow field so that a new 
Open will re-create the window; it deletes the DA's menu and 
disposes of the heap space occupied by window and menu, then 
it redraws the menu bar. Close is called automatically by the 
Desk Manager when the close box of the DA window is clicked, 
or Close is selected from the File menu of an application where 
the DA was called. 

The Prime and DrStatus routines are not needed here, and 
will do nothing at all. 


Sending messages to the DA 
The heart of the desk accessory is the Ctl routine. This 


routine will receive a message from the desk manager to indicate 
which action should be taken - a very simple implementation of 
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object-oriented behavior, in fact. I have written a shell routine 
that handles some of the actions of a desk accessory; all other 
actions simply do nothing, but since they are included in the case 
statement, you can very easily add your own routines. 

The message code is contained in the csCode parameter, 
which is in the parameter block whose address was passed in AO 
when Ctl was called. Ten messages are possible: 


-1:  'good bye kiss' that will be given just before an applica- 
tion exits to the finder; 

64:  anevent should be handled; 

65: take the periodic action that has to be performed by the 
DA. This message is sent every time the number of ticks 
in the drvrDelay field of the DA header has expired; 

66: The cursor shape should be checked and changed if 
appropriate. This message is sent each time SystemTask 
is called by the application, as long as the DA is active; 

67: A memu selection should be handled. csParam contains 
the menu ID and csParam+2 the menu item number; 

68: handle Undo command from the Edit menu; 

70: handle Cut command; 

71: handle Copy command; 

72: handle Paste command; 

73: handle Clear command. 


The example implements handlers for the first five actions; 
no Edit menu selections are handled. The periodic action simply 
consists of a short beep once every second. (You might want to 
change this to save your sanity if you really wantto do something 
useful with this desk accessory). The goodBye action is also a 
beep, but 50 ticks long. When the desk accessory is active and you 
close an application, it will sound almost as if the system reboots. 
Don't let yourself be bothered by this. 

The accCursor message will call update-cursor, which 
checks whether the mouse is inside the DA window and changes 
the cursor to the standard NNW arrow, if necessary. 

The menu and event handlers are a little more complicated. 
First, since both will output text to the DA window, we have to 
write some rudimentary output routines; the Mach2 output rou- 
tines won't work without the kernel. tp will type a string in the 
current grafPort, and crd acts the same way as cr in the Forth 
kernel. I've also included some numeric output routines, which 
you might find convenient to use; they are not needed for the 
example, although I used them in debugging. 


The event handler(s) 


The DA's response to the accEvent message has to be 
subdivided according to the event that has happened. Therefore, 
we check the what field of the event record and set up another 
case statement that contains the handlers for each type of event. 
The behavior that we'll give to our DA window is that of a 
document window with zoom box and size box that responds to 
mouse down and key down events by displaying appropriate 
messages in the window. The DA's own menu should be dis- 
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played when the window is activated and removed when it is 
deactivated. 

The activate handler, therefore, first checks whether the 
window is activated or deactivated, gets the menu from the 
resource file in the first case and attaches it to the menu bar, or 
deletes it in the latter case. 

The update handler will clear the update region and redraw 
the grow icon. Key down events will clear the window and 
display a message in the first line. 

Mouse down events cannot be handled as easily as with 
application windows. If you call findWindow when the mouse is 
clicked in a desk accessory window, the code returned is always 
2 (= in system window), no matter what part of the system 
window was clicked. The drag region and close box are handled 
by the desk manager, so no problem there; but we have to check 
ourselves for clicks in the size or zoom box. This is especially 
annoying for the zoom box, because we also have to keep a record 
of the current zoom state of the window. With application 
windows, the window manager takes care of this task, changing 
the part code that is returned by FindWindow depending on 
whether we have to zoom in or out. 

I defined the words ?inGrow and ?inZoom that return true 
when the mouse click (in local coordinates) was in the size box 
or in the zoom box of the active window. The zoom state has to 
be maintained by a flag. The mouse down event handler will 
check for size box and zoom box clicks and change the window 
accordingly. The region that comprises the grow icon - which is 
part of the content region - will have to be added to the update 
region after the window has been made smaller or before it is 
enlarged. The word invalsize has been defined for this purpose; 
for resizing with the size box, we just call it before and after the 
resizing since we don't know the new window size. For zooming, 
we Call invalsize before zooming in and after zooming out. 

If the mouse is clicked in the content region, the window 
responds simply by typing a message, followed by a new line. 


This takes care of mouse down events; now menus are the 
last thing we have to include. If the accMenu message is received 
by the DA, the menu item number is extracted from the parameter 
block and a message displayed according to the item number. 
Add any of your own routines here if you like. 


Getting the DA started 


To add the desk accessory to your system file, just load the 
Forth program and type make-DA. This will create a file "Mach2 
DA .rsrc" on the default disk. Then run RMaker with the input 
given in listing 2, which will give you a small briefcase called 
"Mach2 ОА". It contains the DRVR, MENU and WIND re- 
sources and may be used as an input to the Font/DA Mover to 
install the desk accessory in the system file. Good luck (you don't 
really need it, though). 


Using the template to write 'useful' DAs 
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In the unlikely case that you would want to beef up the DA 
example to do something really useful, you should be careful 
about a couple of things. 


First, make sure that no Forth word you use in yout routines 
makes part of the Mach2 kernel. This can easily be checked by 
including the word in a simple definition and disassembling it. If 
you see a JSR to a jump table entry or a JSR xxx(A5) at the 
position of the word, you can't use itin a DA. JSRs are only legal 
if they point to routines that you defined yourself. The only 
Mach2 words you may use are those that directly compile 68000 
code; fortunately, there are quite a few of them. Some others you 
have to redefine: the multiply and divide operators, for example. 

Second, A6 stack space may become a problem if your 
routines get more complicated. This is easily taken care of, but 
equally easy to overlook. 

Third, if you redefine any general purpose routines that 
create kernel-independent code and could be useful to others in 
writing their DAs, don't hesitate to drop me a line. Nothing is 
more frustrating than having to reinvent the wheel... 


Listing 1: Desk Accessory written in Mach2 


( Mach2 desk accessory with owned resources ) 
( J. Lengowski / MacTutor Nov. 86 ) 


only forth also assembler also mac 


HEX 
44525652 CONSTANT "drvr 


BINARY 
0000 110111101018 CONSTANT DAEmask 


С *** System globals *** ) 
HEX 
8FC CONSTANT JioDone 


DECIMAL 
С windowrecord fields, starting with grafport ) 
16 CONSTANT  portRect С Grafport rectangle ) 


( fields of WindowPeek ) 
108 CONSTANT windowKind 
119 CONSTANT wVisible 
111 CONSTANT wHiLited 
112 CONSTANT goAwayF lag 
113 CONSTANT spareF lag 
138 CONSTANT dataHandle 
140 CONSTANT controlList 
152 CONSTANT refCon 


( fields of device control entry ) 
4 CONSTANT dCtlFlags 
6 CONSTANT dCt1QHdr 
16 CONSTANT dCtlPosition 
20 CONSTANT dCtlStorage 
24 CONSTANT dCtlRefNum 
26 CONSTANT dCtlCurTicks 
30 CONSTANT dCtlWindow 
34 CONSTANT dCt'Delay 
36 CONSTANT dCtlEMask 
38 CONSTANT dCtlMenu 


( csCodes for Ctl calls ) 


-1 CONSTANT goodBye 
64 CONSTANT accEvent 
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65 CONSTANT accRun 

66 CONSTANT accCursor 
67 CONSTANT accMenu 
68 CONSTANT accUndo 
76 CONSTANT accCut 

71 CONSTANT accCopy 
12 CONSTANT accPaste 
T3 CONSTANT accClear 


X*** standard parameter block data structure *** ) 


( 

@ CONSTANT qLink 
4 CONSTANT 
6 
8 


аТуре С queue type ) 

CONSTANT ioTrap С routine trap 2 

CONSTANT ioCmdAddr С routine address ) 
12 CONSTANT ioCompletion C addr of completion routine ) 
16 CONSTANT ioResult С result code returned here ) 
18 CONSTANT ioNamePtr С pointer to file name string) 
22 CONSTANT ioVRefNum С volume reference number ) 
24 CONSTANT ioRefNum 
26 CONSTANT csCode С type of control call ) 
28 CONSTANT csParem С control call parameters ) 


С pointer to next queue entry ) 


( *** eventrecord data structure *** ) 


0 CONSTANT what 

2 CONSTANT message 

6 CONSTANT when 

19 CONSTANT where 

14 CONSTANT modifiers 


( *** event codes *** ) 
0 CONSTANT null-evt 

1 CONSTANT mousedn-evt 
2 CONSTANT mouseup-evt 
3 CONSTANT keydn-evt 

4 CONSTANT keyup-evt 
5 CONSTANT autokey-evt 
6 CONSTANT update-evt 
7 CONSTANT disk-evt 

8 CONSTANT activate-evt 
19 CONSTANT network-evt 
11 CONSTANT driver-evt 


CODE shi С data "bits ) 
MOVE.L CA6)+, DØ 
MOVE.L CA6),D1 


LSL.L 00,01 
MOVE.L D1, CA6) 
RTS 


END-CODE MACH 


CODE shr С data "bits ) 
MOVE.L CA6)+,D8 
MOVE.L CA6),D1 


LSR.L 00,01 
MOVE.L 01, CA6) 
RTS 


END-CODE MACH 


( *** start of desk accessory main code *** ) 


header testDA C marker for writing to DRVR resource ) 


header drvrFlags 2 allot 
header drvrdelay 2 allot 
header drvrEMask 2 allot 


header drvrMenu 
header drvrOpen 


2 allot 
2 allot 


header drvrPrime 2 allot 
header drvrCtl 2 allot 


header drvrStatus 


2 allot 


header drvrClose 2 allot 
header drvrname 32 allot 


( *** main desk accessory routines *** ) 
C for storage of old grafPtr ) 


header oldPort 4 allot 
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header temprect 8 allot 

header SizeRect 8 allot ( grow size limits ) 
header mouseLoc 4 allot ( mouse location ) 
header NewSize 4 allot ( for SizeWindow ) 
header penLoc 4 allot ( pen location ) 


header tempString 256 allot С for numeric conversion etc. ) 


header zoomState 4 allot € zoomed in or out ) 


: whereMouse ['] mouseLoc call getMouse ['] mouseLoc ё ; 


: cl С WPtr -- ) portrect + call eraserect ; 
: tp call drawstring ; 


: crd ['] penLoc call getpen 
10 € horizontal boundary ) 
(“1 penLoc wê 12 + 
call moveto 


) 


CODE NumToStr ing 
MOVE.L (A62*,A0 
MOVE.L (A62,D0 
MOVE.W 80,-(АТ) 
Pack7 
MOVE.L A®,CA6) 
RTS 

END-CODE 


CODE StringToNum 
MOVE.L CA6), Ad 
MOVE.W #1,-CA7) 
-РаскТ 
MOVE.L D®,CA6) 
RTS 

END-CODE 


CODE unpack 
MOVE.L (А62,00 
CLR.L D1 
MOVE.W 00,01 
CLR.W DØ 
SWAP .W DØ 
MOVE.L 00, (Аб) 
MOVE.L D1,-CA6) 
RTS 

END-CODE 


CODE pack 
MOVE.L (A6)+,D1 
MOVE.L (А62,00 
SWAP.W DØ 
MOVE.W 01,00 
MOVE.L 00, CA6) 
RTS 

END-CODE 


: .dC num -- ) Г1 tempstring NumToString tp ; 
( *** event-handling routines *** ) 


: activate-handler ( menuID DAWind event-rec | -- ) 
event-rec modifiers + w@ 1 and 
IF € window activated ) 
menuID call getRMenu 0 call InsertMenu 
call drawMenuBar 
ELSE С window deactivated ) 
menuID call deleteMenu 
menuID call getRMenu call DisposMenu 
call drawMenuBar 
THEN 


: update-handler ( DAWind event-rec | -- } 
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("1 penLoc call GetPen 
DAWind CALL BeginUpdate 
DAWind cl 
DAWind CALL DrawGrowIcon 
DAWind CALL EndUpdate 
['] penLoc 2+ иё ['] penLoc wê 
call moveto ( restore pen position ) 


: ?inGrow ( localPt WPtr | b r -- flag ) 


WPtr portRect + 4 + 

dup wê -> b 2+ wê -> г 

['] temprect r 14 - b 14 - r b call setrect 
localPt ['] tempRect call PtInRect 


: ?inZoom ( locelPt WPtr | г -- flag ) 


WPtr portRect + 6 + иё > г 
['] temprect r 20 - -16 r8- -4 call setrect 
locelPt ['] tempRect call PtInRect 


: invalSize ( Рогі | br -- ) 


gPort 4 + wê -> b 

gPort 6 + иё > г 

['] temprect г 16 - Ø r b call setrect 
['] tenprect call invalrect 

("1 temprect Ø b 16 - r b call setrect 
(“1 temprect call invalrect 


: mousedn-handler ( DAWind event-rec | whereM DAPort -- ) 


DAWind portrect + -> DAPort 
event-rec where + 6 -> whereM 
whereM ['] mouseLoc ! 
['] mouseloc call GlobalToLocal 
['] mouseloc 8 dup 
DAWind ?inGrow 
IF A DAPort invalSize 
DAWind whereM ['] SizeRect call GrowWindow 
DAWind swap unpack swap -1 call sizewindow 
DAPort invalSize 
ELSE 
DAWind ?inZoom 
IF ('] zoomState @ 
IF Ø ['] zoomState ! 
DAWind whereM 7 call TrackBox 
IF DAPort invalSize 
DAWind 7 Ø call ZoomWindow THEN 
ELSE 1 ['] zoomState ! 
DAWind whereM 8 call TrackBox 
IF DAWind 8 8 call ZoomWindow 
DAPort invalSize THEN 
THEN 
ELSE € in content region ) 
" Mouse down" tp crd 


: update-cursor ( DAWind | -- } 


whereMouse DAWind portrect * call PtInRect 
IF call InitCursor THEN 


: getDrvrID ( dCtlEntry | -- па) 


dCtlEntry dCtlRefNum + иё 1 ext 
i+ negate 


: ownResID € resID drvrID ) 


9 sh] + -16384 + 
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: Open ( DCtlEntry ParamBlockRec | DAWind -- ) 4 OF " Item4!" tp crd ENDOF 


['] oldPort call GetPort 6 OF " Item6!" tp crd ENDOF 
dCtlEntry dCtiWindow + ё ENDCASE 
ø= IF ( not open already ) 0 call HiLiteMenu 
0 dCtlEntry getDrvrID ownResID ENDOF 
dup dCtlEntry DCtlMenu + w! accUndo OF =  ENDOF 
С menu ref has to be updated ) accCut OF X ENDOF 
0 Ø call getNewWindow -> DAWind accCopy OF ENDOF 
DAWind dCtlEntry dCtlWindow + ! accPaste OF ENDOF 
( store window pointer ) accC lear OF ENDOF 
DAWind dCtlEntry dCtlRefNum + wê ENDCASE 
swap windowKind + w! ['] oldPort @ call setPort 
DAWind call setport р 
@ ['] zoomState ! 
("1 sizerect 50 50 500 320 call setrect : DrStatus ( DCtlEntry ParamBlockRec | -- ) 


1010 call moveto 
("1 oldPort ё call setPort 


Г 


ТНЕМ : Prime ( DCtlEntry ParamBlockRec | -- } 
; ; 
: Close ( DCtlEntry ParamBlockRec | -- ) ( *** glue routines *** ) 
dCtlEntry dCtlWindow + header local.stack 200 allot 
dup @ call DisposWindow 0 swap ! 
C so that Open will work again ) CODE setup. local.stack 
DCtlEntry DCtlMenu + мё С get menu ID ) LEA -8CPC),46 С local stack grows downward from here ) 
dup call deletemenu RTS 
call getRMenu call disposMenu call drawMenuBar END-CODE 


CODE DAOpen 
MOVEM.L A0-A1,-CAT) 


( DCtlEntry ParamBlockRec | DAWind event-rec menuItem -- ) setup. local.stack 
MOVE.L A1,-CA6) 
("1 oldPort call GetPort MOVE.L А@,-(Аб) 
dCtlEntry dCtlWindow + 8 dup -> DAWind call setport Open 
ParamBlockRec csCode + wê 1] ext CLR.L DO 
CASE MOVEM.L CA72*,A0-A1 
goodBye OF 50 call sysbeep ENDOF RTS END-CODE 
accEvent OF 
ParamBlockRec csParam + 8 -> event-rec CODE DAClose 
event-rec what + wé MOVEM.L A®-A1,-CA7) 
CASE setup. local.stack 
mousedn-evt OF MOVE.L A1,-CA6) 
DAWind event-rec mousedn-handler ENDOF MOVE.L А0,-САб) 
Close 
keydn-evt OF DAWind cl CLR.L 00 
DAWind call DrawGrowIcon MOVEM.L (А72%,А0-А1 
10 10 call moveto " Key down." tp сга RTS END-CODE 
ENDOF 
CODE DACtI 
eutokey-evt OF X ENDOF MOVEM.L Аб-А 1,-САТ) 
setup. local.stack 
update-evtOF MOVE.L A1,-CA6) 
DAWind event-rec update-handler ENDOF MOVE.L А0,-САб) 
Ctl 
disk-evt OF ЕМООР CLR.L DØ 
MOVEM.L CA7)+,AQ-A1 
activate-evt OF MOVE.L JioDone, САТ) 
DCtlEntry DCtiMenu + wê С get menu ID ) RTS END-CODE 


DAWind event-rec activate-handler  ENDOF 
CODE DAStatus 


network-evt OF  ENDOF MOVEM.L AQ-A1,-CAT) 
driver-evtOF ^ ENDOF setup. local.stack 
MOVE.L Ai,-CA6) 
ENDCASE MOVE.L А0,-(Аб) 
DrStatus 
ENDOF CLR.L 00 
MOVEM.L CA72*,A0-A1 
accRun OF 1 call sysbeep ENDOF RTS END-CODE 
accCursor OF DAWind update-cursor ENDOF 
accMenu OF CODE DAPrime 
ParamBlockRec csParam + 2% мё 1 ext MOVEM.L А0-А1,-(А7) 
CASE 1 OF " Item1!" tp сга ENDOF setup. local.stack 
2 OF " Item2!" tp crd ENDOF MOVE.L A1,-CA6) 
3 OF " Item3!" tp crd ENDOF MOVE.L A@,-CA6) 
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Prime 

CLR.L DØ 

MOVEM.L (А72%,А0-А1 
RTS END-CODE 


header endDA 
С *** code written to DRVR resource ends here *** ) 


С xxx initialization routines *** ) 


: SetFlags ['] drvrFlags w! ; 
: setDelay ('] drvrDelay w! ; 
: setEMask ('] drvrEMask w! ; 
: setMenuID ['] drvrMenu w! ; 
: setOpen ['] drvrüpen  w! ; 
: setPrime [') drvrPrime w! ; 
: бейей "1 drvrCt] w! ; 
: setStatus ['1 drvrStatus w! ; 
: setClose ['] drvrClose w! ; 


: setName ( addr len | target -- ) 
("1 drvrName -> target 
len target c! 
eddr terget 1* 
len 31» if 31 else len then 
cmove 


~ 


write resource to file ) 

: $create-res ( str-addr - errcode ) 
call CreateResFile 

call ResError L_ext 


: $open-res ( addr | refNum - refNum or errcode ) 
addr call OpenResFile -> refNum 
call ResError L.ext 
?dup IF ELSE refNum THEN 


: close-res ( refNum - errcode ) 
call CloseResF ile 
call ResError L. ext 


: make-res ( addr len rtype ID name | -- ) 
eddr len call PtrToHand 
abort" Could not create resource handle" 
rtype ID name call AddResource 


: write-out ( filename | refnum -- ) 
filename $create-res 
ebort" That resource file alreedy exists" 
filename $open-res 
dup Ø< abort" Open resource file failed" 
-) refnum 
refnum call UseResF ile 
['] testDA (') endDA over - 
"drvr 12 " Mach 2 DA" make-res 
refnum close-res abort” Could not close resource f ile" 


: install-system ( | refnum -- ) 
" System" $open-res 
dup 0< abort" Open resource file failed" 
-) refnum 
refnum call UseResF ile 
"drvr 25 call getresource call rmveresource 
('] testDA [') endDA over - 
"drvr 25 " Mach 2 DA" make-res 
refnum call UpdateResF ile 
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: init-DA 
( initialize offsets ) 
['] DAOpen ['] testDA - . setOpen 
['] DAPrime['] testDA -  setPrime 
С") DACt] ['] testDA - бейсі 
[') DAStatus ['] testDA -  setStatus 
("1 DAClose['] testDA -  setClose 
initialize driver name ) 
" Mach 2 DA" count setname 
initialize driver flags, NeedTime, NeedGoodBye, CtlEnable ) 
[ hex 1 3400 setFlags [ decimal ) 
initialize delay time ) 
68 setDelay 
initialize event mask, events recommended in IM ) 
DAEMask setEMask 
initialize menu ID, local 10=0 for DRVR ID=12 ) 
- 16000 setMenuID 
€ careful! this field will NOT be changed 
by the DA Mover when ID is changed ) 


“м м ум ум "^ 


: make-DA 
init-DA 
" Mach2 DA.rsrc" write-out 


: install-DA init-DA install-system bye ; 


Listing 2: RMaker input 
file for the DA example 


* Resources for MACH 2 
desk accessory J. Lengowski 1986 


Mach2 DA 
DF ILDMOV 


INCLUDE Mach2 DA.rsrc 


Type MENU 
~ 16000 
My DA 
Item 1 
Item 2 
Item 3 
Item 4 
(- 
Iten 6 


Type WIND 

," 16000 
Mach2 Desk Accessory 
100 131 300 381 
Visible GoAway 
8 
0 


em. 


Sel 


cad 
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Forth Forum 
Introduction to SCSI Devices 


In this article Jórg introduces us to the SCSI routines. Last 
month, Tim Standing began a series on building a hard disk. Next 
month, Tim Standing will continue his series with the SCSI driver 
and formatting program that detects bad disk blocks for his hrad 
disk project. Until then, this article should help us prepare for the 
world of SCSI devices from the Forth perspective. 

If you have investigated the possibility of building the hard 
disk published last month, then you know that prices for SCSI 
hard disks have gone down rapidly even as I write this. And, 
starting with a naked hard disk drive, a controller card and a 
power supply, it shouldn't be that difficult to get a hard disk 
system going, since an example of a (buggy) SCSI driver has 
already been published several months ago in the Software 
Supplement by Apple. While we wait for Tim Standing's SCSI 
example, here are some of my thoughts on the several obstacles 
that have to be overcome by the naive-thinking person (like me) 
who just wants to plug it all together and have those 20, 40 or 
more megabytes of extra space (in my case, it was an 80 
megabyte unit from Quantum Co. with an integrated SCSI 
interface). The first problem, and the major one, is to write a 
driver for the particular SCSI device. Even though starting from 
Apple's example makes the job casier, it is by no mcans trivial to 
adapt the generic driver to your particular kind of disk reliably. 

We'll return to that point later; first, I have to apologize for 
not being able to print the source code of Apple's SCSI driver in 
our magazine (for copyright reasons). However, for anybody 
interested this code should be easy to come by, either from the 
Software Supplement or by downloading it from Delphi or 
Compuserve. For those of you familiar with drivers, I'll give a 
short description of what it does; we'll start with a review of the 
organization of an SCSI device (also given in IM). 


SCSI devices on the Mac» 

The SCSI driver resides on the SCSI disk at a position given 
in the device descriptor map (DDM), which is always block 0 of 
the SCSI device. Here, the positions and lengths of the drivers 
available on the disk are stored. Inside Mac describes its format: 
( ***The layout of blk О of a bootable SCSI device*** ) 

( Forth Format ) 


HEX 

4552 CONSTANT SBSigWord (block 0 signature ) 
0 CONSTANT SBSig ( signature word ) 
2 CONSTANT SBBlkSize (block size of device ) 
4 CONSTANT SBBlkCount  ( # blocks on device ) 
8 CONSTANT SBDevType (device type code ) 
A CONSTANT SBDevID 
C CONSTANT SBData ( start of data section ) 
10 CONSTANT SBDrvCount ( # drivers to follow ) 
12 CONSTANT SBDrvrs ( start of driver descriptors ) 
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( Driver descriptors) 
0 CONSTANT DDBlock 
4 CONSTANT DDSize 
6 CONSTANT DDType 


( physical block of driver ) 

( block count of driver ) 

( Processor type of driver ) 
( Macintosh = 1 ) 


Block 1 of the disk is supposed to contain the device 
partition map (DPM), which describes the various partitions into 
which the disk may be split up. (In our case, we'll work with one 
partition only). The format of the DPM is as follows: 

( ***The layout of blk 1 of a bootable SCSI device*** ) 
(in Forth format ) 
HEX 
5453 CONSTANT PDSigWord (block 1 signature ) 
0 CONSTANT PDSig ( PDSigWord goes here ) 
2 CONSTANT PDsStart ( starting block of partition ) 
6 CONSTANT PDSize ( # blocks in partition ) 
A CONSTANT PDFSID 
( File System ID of partition creator or NIL ) 
( 'TFS1' for Macintosh ) 


In the case of a disk which will only be accessed by a 
Macintosh, block 2 and the following blocks then contain the disk 
driver code. 

As you may recall, the standard format of a driver consists 
of a header in which offsets to the five driver routines Open, 
Close, Control, Status and Prime are kept, followed by the 
routines themselves (see my last article). The SCSI driver, 
however, must contain not only those routines, but also some 
means to install itself at the time the system boots up, so that the 
hard disk will be bootable. 

Therefore the SCSI driver code starts with aJMP instruction 
to the installation routine. The routine that Apple provides will 
check whether the SCSI disk is compatible with the Macintosh 
operating system ( that means that the 'signatures' of block 0 and 
1 are correct, the driver type is =1, and the file system ID is 
TFS1), and if so, create a device control entry for the driver and 
install it. The system then knows that a new disk is present and 
will make it available for use. 

Other routines provided in the generic driver code are those 
for opening, block read/write, eject and getting the SCSI disk 
icon. See Apple's source code for a detailed description. 

The important part that will concern us here is how to read 
or write a block on an SCSI disk, which leads us to the second 
problem that one encounters when trying to hook up a hard disk 
to the Mac Plus. 


SCSI input/output - a quick overview 
Apple, in its infinite wisdom, has decided to leave two 
important things open as an 'exercise to the reader' (sound 
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familiar?). First, there is no utility that detects (maybe on boot- 
up?) whether an SCSI device is present, and initialize it using the 
standard initialization dialog. For doing this, of course, a general 
purpose SCSI driver would have to be contained in either the 
System file or in ROM that can then be used for accessing the 
disk. But since SCSI devices are not quite standardized well 
enough, Apple might have left that out on purpose. 

Second, the SCSI routines in ROM provide only very low- 
level support. Since, as you'll soon see, the same SCSI command 
sequences occur over and over again when working with the 
SCSI bus, Apple should have provided a routine that puts it all 
together (and they promise to do so, actually, in one of their next 
System releases, perhaps in the new Macs, recently announced). 

Since such support was not available at the time I wrote this, 
I wrote some routines that simplify SCSI handling; this shall be 
the subject of this month's column. 


SCSI command sequence 

The sequence of commands that has to be executed to 
transfer information to or from an SCSI device is quite compli- 
cated. This has to do with the fact the the SCSI bus can be in 
different 'phases' depending on the state of the control lines. ГЇЇ 
not discuss the electronic details here, but just give a description 
of the events as they happen one after the other. 

First, the device which initiates the transfer (the 'initiator') 
has to get control of the bus. This is done by executing the 
SCSIGet command from the SCSI manager. Only one device 
can have control of the bus at each time; in our case this will most 
probably be the Macintosh. The initiator then selects a target to 
transfer data to or from; this is done by calling SCSISelect with 
the target's address as a parameter. Each address corresponds to 
one bit of the data bus, so there may be a maximum of eight SCSI 
devices on one bus. The Macintosh has address 7, corresponding 
to the highest bit. Usually, if only one SCSI device is connected, 
itll have address 6. АП of the following examples refer to this 
setup. 

Once SCSIGet and SCSISelect have been called, the link 
between two devices is established and data transfer may begin. 
The story becomes more complicated here since there are four 
types of data that are transferred: commands, 'real' data, status 
information and messages. Data are always exchanged byte-wise 
using two command lines for a handshake protocol. The type of 
the data is determined by the setting of other control lines on the 
bus. 

The transfer sequence generally proceeds in the following 
way: The initiator sends a command to the target. After the 
command has been accepted by the target there can be an 
exchange of 'real' data on the bus, either from the target to the 
initiator (Read) or the other way (Write). There are also com- 
mands that are not followed by any data transfer. 

When the data has been exchanged, the target will have 
some additional information ready as to whether the command 
has been completed successfully, and for more complicated 
commands, extra messages. 

Again, SCSI manager routines are provided for each step of 
this sequence. The command is sent by the means of the 
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SCSICommand routine, which accepts as parameters the ad- 
dress of a command block and its total length in bytes. After 
execution, it will return a status code which is zero if the 
command has been sent successfully. 

Typical command blocks are given in listing 1. All the 
blocks defined there are preceded by their length; a convention 
that is used by my routines. The SCSI commands are standard- 
ized in some way: a Read command, for any device, will be six 
bytes long, the command code in the first byte is always $08, and 
the start position and the number of bytes to transfer are always 
kept in the same fields of the command block. 

When a Read command has been issued, the target will be 
ready for transferring the requested number of bytes. The Macin- 
tosh gets the data through either of two commands: SCSIRead 
or SCSIRBlind. For a normal Read a handshake is performed on 
every byte transfer; for ablind Read the Mac just assumes that the 
target is ready to provide the data at the maximum speed with 
which it can be read, which is 384 KBytes/sec. This often works, 
but has to be tested in each individual case. 

Commands that transfer data from the initiator to the target 
are handled by SCSIWrite or SCSIWBlind in an analogous 
manner. 

The parameter that is passed to the SCSI read/write routines 
is the address of a transfer instruction block, a short sequence of 
instructions, each 10 bytes long, that form a pseudoprogram. 
That way one single read may be executed in chunks of - for 
example - 512 bytes each. As an example let's look at the SCInc 
instruction: it consists of the command word ($0002), a long 
word buffer address addr, and a long word byte count n. When 
this instruction is executed by the SCSIRead command, n bytes 
will be transferred to/from the buffer starting at addr, and the 
buffer address - in the pseudoprogram - will be incremented by 
n. For the SCNolInc instruction, the buffer address is left un- 
changed. 

The pseudoprogram may contain looping instructions so 
that the same sequence of transfers is executed a defined number 
of times. In the simple example, I'm not using any of those 
instructions, but only an SCNoInc followed by an SCStop. This 
is what Apple recommends you to do in any case, because there 
is a bug in the SCSI handler in ROM that screws up multi-block 
transfers. This bug is supposed to be fixed by a patch in System 
3.2, but I sull had problems even with 3.2. 

In summary, to read n bytes from an SCSI device into a 
buffer starting at addr one would have to: 

- store addr and n in the appropriate fields of the 
pseudoprogram block, 

- сай SCSICmd with a pointer to the command block 
for the Read command and the command length on the stack, 

- call SCSIRead or SCSIRBlind with a pointer to the 
pseudoprogram block on the stack. 


After executing this sequence, the transfer would either 
have been completed successfully, or the target would have some 
extra information waiting about what went wrong. In order to 
check successful execution of the command, SCSIComplete is 
called. This routine takes three parameters, a tick count, and the 
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addresses of two variables, message and status. The tick count 
is the timeout that the Macintosh should allow for completion of 
the command (successful or non-successful). After completion, 
two additional types of information are transferred over the bus, 
namely status information and messages from the target to the 
identifier. The status information is always one byte which is zero 
when everything went o.k., the message may consist of several 
bytes, but in our case is always one byte =0. 

The mostcommon status apart from zero (2OK) is status=2, 
which means check condition. You should the issue a Request 
Sense command to the SCSI device in that case to find out exactly 
what unusual condition occurred. The format and meaning of the 
data returned by Request Sense varies depending on the device. 
Acommon condition that occurs with some newer SCSI control- 
lers directly after a reset of the bus (by the SCSI Reset command) 
is Unit attention, which is meant to tell the system that this 
particular unit needs attention because - forexample - it just came 
back from a reset or power-up. The problem here is that on boot- 
up, the Macintosh resets the SCSI bus and expects to be able to 
read immediately from the hard disk. Since no Request Sense 
has been issued, however, the read fails and the Mac can never 
boot from the hard disk. The only remedy is to use a controller on 
which the Unit Attention feature either isn't installed or can be 
disabled. 

After a successfully completed SCSI command, however, 
SCSIComplete should return zeroes in both message and 
Status. 

Let's summarize the complete SCSI command sequence: 

*«SCSIGet gets control of the bus for the Mac, 

eSCSISelect selects the target device, 

eSCSICmd issues a command to the target, 

eSCSIRead, SCSIRBlind, SCSIWrite, SCSIWblind are 
used - if necessary - to transfer data to/from the target, 

eSCSIComplete waits until the data transfer is completed 
or a timeout has expired and returns the status and message bytes 
of the target. 


In order to facilitate the handling of this command se- 
quence, five higher-level words are defined in listing 1: doscsi 
for commands that require no data transfer, doscsi.r and 
doscsi.rb for normal and blind reads, and doscsi.w and 
doscsi.wb for normal and blind writes. The parameters to those 
routines are, from bottom to top on the stack: 

- the timeout tick count; 

- apointer to the command block, the first byte of this block must 
contain the length of the command following it; 

- the device number; 


and in addition for the data transferring commands 


- a pointer to the data buffer; 
- the number of bytes to transfer. 


A number of standard SCSI command blocks are also 
predefined in the listing. Using these commands and the high- 
level words, SCSI handling becomes much easier. 
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Youcan now go ahead and try to install your hard disk driver 
(as mentioned earlier, you should get the generic driver source 
from Apple for this purpose). The strategy is as follows: 

Read the resource that contains the assembled driver code 
into memory. Using the write.block word, write the driver from 
memory to the disk, starting at block 2. Verify (by re-reading with 
read.block and a quick dump) that the blocks were written OK. 

Now define a device descriptor map (DDM), using the 
format given above, and a device partition map (DPM). Write the 
DDM and DPM to blocks 0 and 1 of the SCSI disk. 

Call mount.scsi. This word reserves a system heap block 
for the driver code and moves the code into that block, then 
emulates what is happening on boot-up by jumping to the 
installation routine. Since the driver looks at the system event 
mask to determine whether we're in the boot up phase, we have 
to set this mask to zero temporarily to fool the driver installation 
code. (Note that we'd be in trouble if we didn't reset it afterwards). 
The driver installation routine also takes a number of input 
parameters that are not mentioned in Inside Macintosh, but only 
in the driver source code by Apple: AO contains a pointer to the 
device partition map (which therefore should have been read 
first), and D5 contains the SCSI ID of the device to be installed. 
The glue routine call.driver is used to call the installation 
routine. 

Assuming you have started from a factory-fresh disk, it still 
remains to install the boot blocks and basic dirctory structure. 
This can be done with the disk initialization package, using its 
function DIZero. Although ГЇЇ leave the Forth code to do the 
initialization for my next column, ГЇЇ shortly describe the 
strategy. DIZero needs a drive number and a disk name to 
initialize the disk. The disk name can be chosen freely; the drive 
number has to be found. What is the drive number of the SCSI 
disk? 

Since we just installed the driver, the SCSI disk will be the 
last element in the drive queue. Therefore, we look in the QTail 
field of the drive queue header (system global $308) for the 
queue element, which contains the drive number in its dQDrive 
field. Actually, the drive number of the first SCSI disk installed 
is 5. 

More about SCSI installation in my next column. We'll 
change subjects a little and hear about an interesting aspect of the 
new Mach 2.1 update. 


AO optimizer in Mach 2.1 

As you might have noticed when disassembling Forth code 
(be it Mach 2, MacForth or any other Forth), the machine is often 
forced to do unnecessary register saves and loads. This happens 
for instance when at the end of one word the contents of DO are 
pushed on the stack, only to pop them off again into DO at the 
beginning of the next word! (See listing 2). When each Forth 
word is called as a subroutine, or through an address interpreter, 
such behavior is a necessary consequence of the threaded-code 
structure. But in a system like Mach2 where many words lead to 
inline 68000 code generation, this leads to ridiculous code 
sequences like 

MOVE.L DO,-(A6) 
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MOVE.L (A6)+,D0 


which translates to: "Give me a break, I have to leave this 
number somewhere for a while... ah... there's the stack... might 
justas well drop it there... ...... OK, now let's pick it up again and 
go on." Not really necessary, is it. (Things like that are known to 
happen in some Pascal code, too). 

The new release of Mach 2, 2.1, automatically recognizes 
some of those situations, especially when DO is involved, and 
removes redundant code (listing 2a). With registers other than 
DO, some optimization is done, too, but you can still find some 
'one-hand juggling’ like MOVE.L D1,D1. 

I'll write more about the Mach 2.1 update and about Mac- 
Forth Plus in my next column. MacForth Plus just arrived here, 
and it seems like a major change and major improvement over the 
older MacForth versions. Wait for a comparison of the two Forth 
systems in the next issue of MacTutor. 


FindWindow trick 

One last remark regarding my last column on writing a desk 
accessory in Mach2. You remember that I rewrote the zoom box 
and size box recognition parts of the mouse click handler, 
because FindWindow always returns a part code =2 if you click 
in a desk accessory window. 

Here's a very clever trick from Kamal Gaddas of our 
developer's club: Before you call FindWindow, change the 
WindowKind field of the desk accessory's window record to a 
value 2 8 to indicate that this is a normal application-created 
window, and the correct part code will be returned. Then change 
the WindowKind back to the (negative) desk accessory reference 
number. 


Listing 1 : 
Mach 2 routines for simplified SCSI bus handling 


С Forth SCSI routines, J. Langowski Dec. 1986 ) 
only forth also mac also assembler 


CODE SCSIReset 
CLR.W -CAT) 
MOVE.W &0,-САТ) 
-SCSIDispatch 
MOVE.W (А72%,00 
EXT.L DØ 
MOVE.L D9,-CA6) 
RTS 

END-CODE 


CODE SCSIGet 
CLR.W -CA7) 
MOVE.W #1,-CA7) 
-SCSIDispatch 
MOVE.W (A72*,D0 
EXT.L 00 
MOVE.L 00,-(САб) 
RTS 

END-CODE 


CODE SCSISelect С TargetID -- SCSIErrorResult ) 
MOVE.L (A62*,D0 
CLR.W -CA7) 
MOVE.W 00,-САТ) 
MOVE.W #2,-CA7) 
-SCSIDispatch 
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MOVE.W CA7)+,D8 


EXT.L 0 
MOVE.L 00,-(А6) 
RTS 

END-CODE 


CODE SCSICmd € buffer count -- SCSIErrorResult ) 
MOVE.L (A62*,D0 
MOVE.L (A62*,D1 
CLR.W -CA7) 
MOVE.L 01, -САТ) 
MOVE.W 00, -САТ) 
MOVE.W 83,-(АТ) 
-SCSIDispatch 
MOVE.W CA72*,D0 
EXT.L DØ 
MOVE.L DØ,-(A6) 
RTS 

END-CODE 


CODE SCSIComplete C waitTicks mess stat -- SCSIErrorResult ) 
CLR.W -САТ) 
MOVE.L CA6)+,-CAT) 
MOVE.L САб 2+, -САТ) 
MOVE.L CA62*,-CA7) 
MOVE.W 84,-CAT) 
-SCSIDispatch 
MOVE.W CA7)+,DØ 
ЕТІ 00 
MOVE.L 00, -САб) 
RTS 

END-CODE 


1 CONSTANT SCInc 
2 CONSTANT SCnoInc 
3 CONSTANT SCAdd 

4 CONSTANT SCMove 
5 CONSTANT SCLoop 
6 CONSTANT SCNop 
7 CONSTANT SCStop 
8 CONSTANT SCComp 


variable scbuf 2048 vallot С general purpose SCSI buffer ) 
variable scmess variable scstat 
( used only within the lower-level routines ) 


create SCSIProg 
scnoinc w, 
0, С buffer address ) 
0, C 8 of bytes to transfer ) 
Scstop w, 


: ?scbuf scsiprog 2+ ! ; 
: »sc®&bytes scsiprog 6 + ! ; 


СГ lower level SCSI routines ) 


: initiate.scsi (С cmdblk device® -- ) 
SCSIGet abort" get error" 
( dev* ) SCSISelect abort" select error" 


С emdblk ) dup 1+ swap сё SCSICmd abort” cmd error" 


: finish.scsi ( "ticks -- message status ) 
C ticks ) 
scmess scstat SCSIComplete abort" 
scmess w@ scstat wé 


complete error" 


C general purpose SCSI handler routines ) 

( five different words ere provided, depending on whether ) 

С - no data phase is necessary : DOSCSI ) 

С - data will be transferred TO the initiator, i.e. the Мас: ) 
с  DOSCSI.R for normal reads, DOSCSI.RB for blind reads ) 
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С - data will be transferred FROM the initiator : 2 


с  DOSCSI.W for normal writes, DOSCSI.WB for blind writes 


: doscsi С ticks cmdblk device" -- message status ) 
initiate.scsi 
f inish.scsi 


: doscsi.r 


“2 


C *ticks cmdblk device! buf "bytes -- message status ) 


^scbytes »scbuf 

initiate.scsi 

SCSIProg cell SCSIRead abort" SCSI reed error" 
f inish.scsi 


: doscsi.w 


С ticks cmdblk device! buf "bytes -- message status ) 


»sc®bytes »scbuf 

initiate.scsi 

SCSIProg call SCSIWrite abort" SCSI write error" 
f inish.scsi 


: doscsi.rb 


( ticks cmdblk device® buf "bytes -- message status ) 


^sc"bytes »scbuf 
initiate.scsi 


SCSIProg call SCSIRBlind abort" SCSI read blind error" 


finish.scsi 


) 


: doscsi.wb 


( ®ticks cmdblk device? buf "bytes -- message status ) 


"scbytes »scbuf 
initiate.scsi 


SCSIProg call SCSIWBlind ebort" SCSI write blind error" 


f inish.scsi 
HEX 
С SCSI command block definitions ) 


( first byte contains command length, 
following bytes the command ) 


create test.rdy.blk 


с, 


0 с, C test unit ready ) 
0 
0 н, С word align ) 
create rezero.blk 
6 c, 
1с, ( rezero unit ) 
0, Ow, 
create reqsense .bik 
с 
3 c, ( request sense ) 
13, С 19 bytes of sense data ) 
O w, 
create format.blk 
6c, 
4 c, С format unit ) 


9 c, ( default formatting 2 
0 с, ( data pattern ) 
„Жр С interleave, ignored by 0200 ) 


9 w, 
create init.blk С for erasing and initializing unit ) 
с, 
4 с, C format unit ) 


10 c, С format using defect list ) 
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0 


с; С data pattern ) 
W, С interleave, ignored by 0200 ) 
и, 


create init.dlist ( defect list for initializing unit ) 
lw, С data pattern bit set ) 


„Жр 
create reassign.blk 
6 c, 
Té; ( reassign blocks ) 
0, дин, 
create read.blk 
6 c, 
8 c, ( read ) 
9 w, бс, C logical block address ) 
0 с, ( ® blocks to transfer ) 
„Жр 
create write.blk 
6 c, 
А с, ( write ) 
9 w, дс, С logical block address ) 
0 c, ( ® blocks to transfer ) 
0 м, 


create seek.blk 


В с, ( seek ) 


9 w, Ø c, C logical block address ) 


create inquiry.blk 


6 c, 
12 c, C inquiry 2 


Ow, 0 


c, 
34 c, ( 34 device bytes returned ) 


9 w, 


create modesel .blk 


15 c, ( mode select ) 


9 c, қ peram list length ) 


Ow, 


( reserve, release, copy - not yet implemented ) 


create modesense.blk 
6 c, 


1A c, ( mode sense ) 


9 c, 


9 c, ( page code ) 


9 c, С allocation length 2 


Ow, 


create startstop.blk 


1B с, C start/stop unit 2 


0 c, C bit 0 = 


0 с, 0 


IMMED 2 


с, 
0 с, C bit Ø = START ) 


( receive/send diagnostics - not yet implemented ) 


create readcap.bik 


с, 
25 с, ( read capacity 2 
9 c, ( bit Ø = RELADR ) 


0 с, Ow, Oc, 


( 4 bytes logical block address ) 
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, 0 с, 
,  €bit 8 = PMI ) 


; 


a Q & 
= с) © 


create readext.blk 


Ac, 

28 c, ( read extended ) 

0 с, ( bit Ø = RELADR ) 

Ow, Oc, ( 4 bytes logical block address ) 


0 c, 
9 c, 
„Жр ( 2 bytes trensfer length ) 
0 ми, 


create writext.blk 


C 
24 c, — C write extended ) 
9 c, C bit 0 = RELADR ) 
Oc, Ow, Oc, ( 4 bytes logical block address ) 


А С 2 bytes trensfer length ) 


create seekext.blk 


с 
28 c, С seek extended ) 
0 c, ( bit Ø = RELADR ) 
Oc, Ow, бс, ( 4 bytes logical block address ) 
9 c, 


С compare - not yet implemented ) 
create verify.blk 


( verify ) 

c, ( bit Ø = RELADR, bit 1 = BYTCHK ) 

c, 0 м, дс, С 4 bytes logical block address ) 
бс 

Ow, (verification length ) 

Q w, 


( read defect deta, read/write data buffer - not yet implemented 
) 


DECIMAL 


6 CONSTANT myDisk С SCSI address of my Disk ) 
variable numstring 20 vallot 
: input-number numstring 1+ 20 expect numstring number? drop ; 


: wait ( nticks | ®ticks -- ) 
call tickcount -> #ticks 
BEGIN pause 

call tickcount *ticks - 
nticks › 
UNTIL 


; 
С SCSI routines follow ) 


: disp.s.m ." Stet, Mess =". . сг; 


: rsc scsireset ." reset code =" . cr; 


: format 600 format.blk myDisk doscsi disp.s.m ; 


: vfy ( | start -- ) 
." enter start block : " input-number 256 /mod 
verify.blk 2+ ! verify.blk 6 + c! 
0 verify.blk 2+ c! 
." enter 8 blocks : " = input-number verify.blk 8 + w! 
6000 verify.blk myDisk doscsi disp.s.m 
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: modesense 
63 modesense.blk 3 + c! 
84 modesense.blk 5 + c! 
120 modesense.blk myDisk scbuf 84 doscsi.rb 
disp.s.m 


: reqsense 
120 reqsense.blk myDisk scbuf 19 doscsi.rb 
disp.s.m 
hex 
20 0 do scbuf i + сё . loop 
decimal 


: Sense modesense scbuf 100 dump ; 


: read.block С block® -- ) 
256 /mod read.blk 2+ w! read.blk 4 + c! 
1 read.blk 5 + c! 
120 read.blk myDisk scbuf 512 doscsi.r 
disp.s.m 


: seek.block С block? -- ) 
256 /mod seek.blk 2* w! seek.blk 4 * c! 
120 seek.blk myDisk doscsi 
disp.s.m 


: write.block С block# -- ) 
256 /mod write.blk 2+ w! write.blk 4 + c! 
1 write.blk 5 + с! 
120 write.blk myDisk scbuf 512 doscsi.w 
disp.s.m 


7 


create ddm 512 allot 
create dpm 512 allot 
create driver .block 2048 allot 


: read.ddm 
Ø read.blk 2+ w! Ø read.blk 4 + c! 
1 read.bik 5 + c! 
120 read.blk myDisk ddm 512 doscsi.r 
2drop 


: read.dpm 
0 read.blk 2+ w! 1 read.blk 4 + c! 
| read.blk 5 * c! 
120 read.blk myDisk dpm 512 doscsi.r 
2drop 


7 


.TRAP = -newptr,sys $45 IE 
hex 144 CONSTANT SysEvtMask decimal 


VARIABLE syshp.drvr 


: install.driver ( | dstart dlength dbytes pointer -- ) 
read.ddm 
ddm 18 + 6-» dstart 
ddm 22 + wê -> dlength 
dlength 512 * -> dbytes 
dstart 256 /mod read.blk 2+ w! read.blk 4 + c! 
dlength read.blk 5 + c! 
120 read.blk myDisk driver.block 512 dlength * doscsi.r 
2drop 
dbytes MOVE.L (A62*,D0 
-newptr,sys ( get memory block in system heap ) 
MOVE.L Аб,-СА6) -» pointer 
pointer 
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IF driver.block pointer dbytes cmove 91D66C: MOVE.L — (A60*,D1 


pointer syshp.drvr ! Ø 1D66E : MOVE.L 00,-САб) 
ELSE ." Not enough system heap for installation." cr 010670: MOVE.L D1,-CA6) 
THEN 010672: RTS 
Й test2 { 
010674: MOVEQ.L —*$3,00 
CODE call.driver 
MOVE.L D5,-CA7) С the following code would have been generated here under the 
MOVE.L CA6)+,D5 previous version and is deleted by the 2.1 optimizer ) 
MOVE.L (A62*,A0 MOVE.L 00, -(А6) 
execute | MOVE.L (A6)+, DØ 
MOVE.L (A72*,D5 
RTS 010676: MOVE.L (A62*,D1 
END-CODE 010678: MOVE.L 00,-САб) 
010674: MOVE.L 01,-(Аб) 
: rdy.scsi 010676: RTS 
scsireset drop 
240 wait C until disk has finished resetting ) b. using newly defined words 
120 reqsense.blk myDisk scbuf 19 doscsi.rb 2drop 
4 CODE test2* 
тоуе.1 Ca62*,d0 
: mount.scsi addq.1 82,40 
rdy.scsi поуе.1 d,-Ca6) 
install.driver rts 
read.dpm END-CODE MACH 
SysEvtMask @ 
@ SysEvtMask ! : testi test2* test 2+ ; 
syshp.drvr @ dpm myDisk call.driver 
SysEvtMask ! CODE testa2+ 
g move.] (a6)+,d1 
addq.1 82,41 
: test.blks 18 Ø do i read.block scbuf 64 dump cr loop ; move.] 41,-(аб) 
rts 
: mount.n.bye mount.scsi bye ; END-CODE MACH 
: read.cap : test2 testa2+ teste2* ; 
120 readcap.blk myDisk scbuf 8 doscsi.rb 
abort" Can't read capacity” drop ~ Disassembler output - 
cr 
." This disk contains " scbuf @ dup . test2+ 
." blocks of "  scbuf 4 + ё dup . ." bytes." сг 91D6C4: MOVE.L (A62*,D0 
." Total capacity is " 1024 */ . ." Kbytes." cr 0106С6: ADDQ.L $2,060 
] 010668: MOVE.L DØ,-CA6) 
Aa ee ee 0106СА: RTS 
test 
Listing 2: 0106СС: MOVE.L CA62*,D0 
Example of code optimization under Mach 2.1 0106СЕ: ADDQ.L *$2,D0 
010600: ADDQ.L 8%2,00 
а. using built-in words 010602: MOVE.L D0,-CA6) 
010604: RTS 
: test 3 ; testa2+ 
: testi swap ; 010606: MOVE.L CA62*,D1 
: test2 3 swap ; 010608: ADDQ.L 8$2,D1 
Ø1D6DA: MOVE.L D1,-CA6) 
' test 10 il 0106006: RTS 
С output by the Mach 2.1 disassembler ) test2 
test 01060Е: MOVE.L (А62%,01 
0 10664: MOVEQ.L %%3,00 $3 0106Е0: ADDQ.L #$2,01 
0 10666 : MOVE.L 00,-САб) 0106Е2: MOVE.L D1,D1 (¢/) 
010668: ЕТ5 0106Е4: ADDQ.L #$2,01 
test 0106Е6: MOVE.L D1,-CA6) 
0 10664: MOVE.L (Аб )+,00 0106Е8: RTS 
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Forth Forum 


MacForth™ Plus 


New Upgrades for MacForth & Mach2 а 


MacForth Plus and Mach 


24 2.1) 


This month I'd like to give you an 
overview of the most recent ver- 
sions of the two Forth implementa- 
tions for the Macintosh that you've 
been reading about most in this 
column. That is, Mach2 (version 
2.1) and MacForth (Plus). NEON, 
making up acategory оп itsown, I'll 
leave out this time. 

Regular readers of this column 
will have noticed that the majority 
of Forth examples have been writ- 
ten in Mach2. This shouldn't be 
meant as a bias towards that par- 
ticular system, only that I think it is 
better to stay consistent and use one 
implementation, pointing out dif- 
ferences to other Forths if they 
arise. 

Let's start with a short descrip- 
tion of MacForth Plus. Since it is a 
major change compared to the older 
versions, it helps to print some 


excerpts of the release notes by Creative Solutions included with 
the system. 


Test 


Sieve (local variables) 
Sieve (stack version) 


1000000 empty loops 


Screen invert 


1 
2 
3 
4 


floating point 


10000 additions 


10000 divisions 
1000 square roots 
1000 sines 

1000 logarithms 


"MacFORTH Plus has been completely rewritten from 
scratch...Most notably, in order to support multi-tasking the file system 
has changed dramatically. Other changes have been made to make 
MacFORTH Plus run much faster, for instance with an entirely new 
method for doing loops. The old system of using the 68000 Trap 
instruction and F-line traps for defining words has been abandoned in 
favor of a system that will work with the 68020 and the 68881 floating 
point coprocessor. This new arrangement is also much faster, but is not 
nearly as compact as the old system. Thus, the kernel is quite a bit larger. 

You will still be able to write applications that will run on 128K 
machines, but it is presumed that for your development environment you 
use at least a 512K machine. 

While block files are still fully supported, MacFORTH Plus also 
provides the ability to write programs in ordinary text files and provides 
an editor as well. Proper use of the editor could change your program- 
ming environment completely, as you can execute a selection range by 
hitting the Enter key. Output will be directed into the file itself. [looks 
very similar to the MPW environment in that aspect - JL]. This 
means you can easily accumulate a lot of information in the file (e.g., by 
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MacForth K2.4MacForth Plus 
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st 


Table 1: Benchmark results of MacForth К 2.4, MacForth Plus and Mach? (version 


execution time (secs) 
Mach2 


19.8 
21.7 


10000 empty loops 


10000 subtractions 
10000 multiplications 


executing WORDS) and read it at your leisure. If you do all your work 
in this way you'll also have a log file recording exactly what you did. 


If you use the system window to input commands, there's a command 
lineeditor. Itsaves the last fourcommands you typed and can be invoked 
at any time to allow you to edit or re-use them. 

Errors are reported by alert boxes in true Macintosh style. 

You can enable and disable the programmer's switch with Ena- 
bleSwitch and DisableS witch. This cannot be guaranteed to work on all 
future Macintosh products, however. 

MacFORTH Plus does multi-tasking. 


A nearly complete set of words is provided for running alerts, modal 
dialogs, and modeless dialogs. 


Words to use resource templates in defining menus, menubars, 
controls, and windows have been added for those who prefer this 
method. 
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The way DO ... LOOP works internally has been changed dramati- 
cally. It's twice as fast as it used to be. There is some cost for the 
additional speed, however. First and most important, I is no longer the 
same as R@. You should not use I or any of its relatives (like IC@, I+, 
J, etc.) unless you are referring to a loop index. The loop index is no 
longer kept on the return stack, but is now in a register. 

Some people will have some rewriting to do to get their old code to 
work because of this. You must be sure you have used I and R@ 
correctly...Second, since the new loops use registers D4, D5, and D6, 
these are no longer available for your own use. 


And finally, the new loop system works somewhat differently in 
extreme cases...This is because the new system checks for the index 
crossing the limit rather than checking how the index is related to the 
limit. (This is actually the method recommended in the Forth 83 
standard.) 


In order to properly support the multi-tasking, it was necessary to 
drop the old FCB system and install a file interface like the Pascal 
interface. 


There are also 3 new variables for I/O redirection: INFILE, OUT- 
FILE, and DEBUGFILE. Input is taken from INFILE; most output goes 
to OUTFILE, except error reports, which go to DEBUGFILE. Any of 
these may be a file, a MacForth wptr, or a device driver. 


Code fields are now 4 bytes long instead of 2. Register allocation has 
completely changed. Vocabularies are set up differently, as is the token 
table (tokens now 6 bytes each). The OBJ resource now includes both the 
old object and the token table (so ROOM will report much larger values 
-- it includes the token table). Most of these changes will impact only 
very advanced users. 

One new feature, contributed by John Baxter, provides for a "Tools" 
Menu. Program development tools can reserve space on and use this 
common menu rather than allocating anew menu for each tool. This has 
already proven to be almost indispensible with the expanding number of 
advanced tools being uploaded to Compuserve, and available through 
the MacForth User's Group. 

Another feature, provided by Tim Hewitt, and now included in the 
default snapshot token, includes any TEXT files that were double- 
clicked on the Finder desktop, if the Option key is held down when the 
files are launched. This is particularly useful for turnkey scripts,.... 
Macintalk support is included... 

Calling procedures and functions written in other Languages: 

This effort is currently in process, (examples are working fine), but 
we are not sure about the format we should use for the interface (Linking 
templates, etc.), and we would like to know what formats end-users 
would like to see (eg. MDS or MPW?). We'll upload the results to 
Compuserve when ready." 


Somuch forthenew features of MacForth Plus as described by 


CSI. Let's now proceed by a more detailed comparison of the two 
Forth systems. 


Speed 
Execution speed is not everything, but it matters a lot. Less if 


you use a lot of toolbox calls; more if you need to write time- 
critical code, as for instrument control, or in heavy number- 
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crunching. 

Listing 1 shows some benchmarks that I used on the two Forth 
systems: a routine that inverts the screen 50 times, the well- 
known Sieve of Erastothenes, one million empty DO...LOOPs, 
and a speed test of the floating point implementation. The words 
counter and timer are not implemented in MacForth and are 
therefore redefined here. 

The figures - given in Table 1 - immediately show that 
MacForth Plus is a great leap forward compared to the MacForth 
К2.4 version. Mach2, however, since it offers the distinct advan- 
tage of generating 68000 code directly instead of going through 
an 'inner interpreter as many other Forths, still executes twice as 
fast (on the average) as MacForth Plus. 

The discrepancy between the two systems is evident for the 
floating point benchmark, with Mach2 executing SANE routines 
5-10 times faster than MacForth. It is not clear to me why the 
floating point routines under MacForth should generate so much 
overhead in an empty loop, but the fact remains. The MacForth 
floating point words themselves (after subtracting the loop over- 
head) execute nottoo much slower than the Mach2 versions; still, 
there is a constant difference of approx. 250 us per floating point 
operator. 

The advantage of the MacForth floating point system is that 
rounding and exception trapping are under very good control 
from your program. In this aspect, Mach2 does not implement the 
full SANE package. 

For faster numerics, there exists a good 32-bit floating point 
package for MacForth in the public domain (Compuserve or 
MacForth Users' Group); for Mach2, see my columns in MT 
V2#7 and V2#8 for 32-bit floating point routines. 

It is not only execution speed that matters but also loading 
speed. Both systems are very fast in loading long files. Although 
I don't have one long program that will load on both systems, I 
tested Mach2 and MacForth Plus with several files of compa- 
rable length and got an average loading speed of about 1.5 Kbyte/ 
sec for Mach2 and 0.8 Kbyte/sec for MacForth Plus (both from 
an SCSIhard disk). Mach2.1 seems to have the edge here because 
of its new hash-coded vocabulary structure; switching off hash- 
ing lets Mach2 load at the same speed as MacForth Plus. 


Debuggers 


MacForth has had a built-in debugger from the very start, and, 
of course, MacForth Plus has kept it. Its TRACE option will 
insert a trace token before each compiled word, so that on 
execution (with the DEBUG feature on) the name of the word 
executed will be printed together with the current stack picture. 
DEBUG output can be redirected to a debug file [this is new], in 
order to leave the screen output undisturbed. 

The stack picture that is displayed with each word helps a great 
deal in analyzing algorithms that do a lot of stack manipulation; 
one can see very quickly whether a routine left something on the 
stack that wasn't supposed to be there, or whether an odd address 
is generated by some bug, etc. 

The MacForth debugger does not really decompile the code 
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since you have to execute it to get it displayed. For decompila- 
tion, however, there exist a number of good tools in the public 
domain. A Forth decompiler included with the system would be 
nice, though, especially since the structure of MacForth Plus 
definitions has changed a lot from the older MacForth versions. 

Debugging under Mach2 is different, due to the different 
implementation that directly generates machine code. Therefore, 
the debugger (included in the v2.1 release) resembles Macsbug 
a lot. You can enter the debugger by selecting a menu option or 
executing DEBUG. This will give you a Macsbug-like window 
that accepts Macsbug-like commands. In addition, you can refer 
to Forth words by their names within the debugger, and when 
code is disassembled, the debugger displays the names of Forth 
words corresponding to the code. JSR-threaded words are 
decompiled without problems this way; if inline code has been 
included using the MACH option, only the most standard defi- 
nitions like swap, drop, literals etc. are recognized. 

Tracing code under Mach2 is more cumbersome than under 
MacForth; you have to set machine-level breakpoints (DEBUG 
«word» sets a breakpoint at the beginning of the definition of 
«word») and then step through the code. Evidently, it is not so 
easy to monitor the stack as with MacForth - the debugger 
displays no stack pictures. 

The interrupt switch for entering the debugger did not work in 
my version of Mach2.1, and Palo Alto Shipping is working on it; 
they promised to have it fully functional Real Soon Now (to steal 
an expression from one of my more famous colleagues). 

My preferred mode of operation is to debug Mach2 code with 
TMON. Forth words are not displayed by name there, true; but 
all the other tools are just so much more powerful. 

For testing out algorithms, I prefer MacForth with its stack 
display on each step while tracing code. You see immediately 
where you've been stupid in your coding. 


Conclusion here: it's really best to have Mach2 and MacForth 
ready for debugging a bigger Forth project... 


Assemblers 


Both MacForth Plus and Масһ2 include an assembler. While 
MacForth Plus uses the Forth philosophy of writing assembly 
code in reverse Polish notation, Mach2 conforms to the standard 
Motorola syntax. 

I suppose one can get used to both assemblers. The reason why 
Iam using the Mach2 assembler in my examples is very simple; 
I still retain hopes that someone from the non-Forth speaking 
community might find at least some of the assembly language 
stuff interesting (and that way gain interest in using Forth as 
well). Seriously, itbecomes much easier to transfer code between 
different programming environments if at least for assembly 
language, one sticks to the standard Motorola syntax. 

The 'forthy' MacForth assembler has the advantage of having 
asetof control structures like if, else, then, begin, while, repeat, 
etc. built in. That, again, makes machine code more readable, but 
raises problems when one deliberately wants to create tight 
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'spaghetti' code (yuck). This is often necessary to squeeze the last 
bit of performance out of a piece of code, and one can generate 
such 'unstructured' code in MacForth by playing some tricks that 
are explained in the manual, but the result will be even less 
readable than in standard assembler using labels. 


Summary: if your program includes large pieces of assembly 
code, I suggest using Mach2, especially if you've been using 
68000 assembly in other environments. For small machine code 
insertions, both systems are probably equivalent. 


Local variables and other data structures 


A great deal of time-consuming and bug-breeding stack 
manipulation can be avoided by using local variables and named 
stack parameters in Forth words. 

Both Mach2 and MacForth offer these options. The syntax is 
not too different between the two systems. In Mach, the word 
name (after the colon) is followed by a parameter list enclosed in 
braces with a vertical bar separating the stack input parameters 
from the local variables: 


: test { абс | loci loc2 loc3 -- comment} ... ; 


while in MacForth the same is accomplished by 


: test 0 1 2 locals| loc3 loc2 loci cba|...; 


initializing loc1, loc2 and loc3 to 0, 1 and 2 at the same time. 
This syntax can be emulated in Mach2 by writing 


: test 012{abcloci loc2 loc3 }... ; 
which makes the two approaches look very similar. 


Local variables (including stack parameters) are limited to a 
maximum of 10 in MacForth Plus, while apparently no restric- 
tion exists in Mach2. In the latter case, a stack frame is generated 
on a local variable stack (A2) that holds four bytes for each 
variable. 

Calling the name of a local variable puts its value on the stack; 
n -»loc1 (Mach2) orn to loc1 (MacForth) stores n into the local. 
Sometimes it becomes necessary to pass the address of a local 
variable to a toolbox routine; in MacForth this is accomplished 
by writing addr.of loc1, and in Mach2 by ^ 1ос1. 


MacForth also includes words for one- and two-dimensional 
array definitions and for data structures. These definitions are left 
as an exercise to the user in Mach2. See MT V2#9 on an alternate 
way of defining structures both in MacForth and Mach2. 


Toolbox interface 


The different philosophy of the implementers of MacForth 
Plus and Mach2 shows up very clearly in the way the Macintosh 
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user interface is handled. While in both systems the most frequent 
elements of the user interface (windows, menus, controls) are 
supported by high-level Forth words, MacForth offers in addi- 
tion, words for handling dialogs, alerts, text edit, events, scrap 
and the drawing routines. This is again consistent with the 
philosophy of keeping the syntax as Forth-like as possible, and 
sometimes makes the code more readable. However, it can create 
problems when transporting algorithms from other programs 
written in C or Pascal, where the toolbox routines are called more 
or less according to the Inside Macintosh standard. 

Mach2, in addition to supporting windows, menus and con- 
trols from within Forth (and linking these structures to the multi- 
tasking environment), gives a very simple way to directly call 
toolbox routines Inside Macintosh style. This is done by writing 


CALL «routine» 


with the appropriate number of parameters on the data (A6) 
stack. Mach2 contains a table of all toolbox routines and most of 
the package calls together with information on how many para- 
meters in which format are expected on the stack. The compiler 
automatically inserts glue code to take the parameters off the A6 
stack (each one occupying 4 bytes here) and pushing them on the 
A7 stack in the correct format. 


For toolbox calls not contained in the list (there are not many), 
or for calling an operating system routine asynchronously, one 
has to write a little piece of assembly code to transfer the 
parameters correctly. Examples of this can be found in almost 
any previous Forth column that deals with Mach2. 

The difference is clear: toolbox calling very 'close to the 
machine' in Mach2, higher level Forth-style toolbox support in 
MacForth. Otherwise the two systems are equivalent, and it is 
again a matter of preference which one to use. For machine-level 
debugging, the subroutine-threaded approach of Mach? is easier; 
on the other hand, with MacForth it might be easier to transport 
code to other window-oriented environments that do not use 
exactly the same toolbox calls as the Macintosh. The problem 
with the MacForth approach, however, is that one has to remem- 
ber a great number of new Forth words for toolbox calls which are 
known by other names in IM. 

Mach2, on the other hand, keeps the IM names (with some 
exceptions), and the handbook contains a very nice quick- 
reference overview about all the toolbox traps with their stack 
parameters which replaces IM in 75% of the cases (the others 
being mostly answered by WinTool). 


Modeless dialogs, which were not supported in earlier Mach2 
versions, can now be used. 


Multitasking 
MacForth now offers multi-tasking support, justas Mach2 had 


from its beginning. The source code of the multi-tasking routines 
is included in MacForth, but not in Mach2. 
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At first glance, multitasking is very similar in the two systems. 
Words are provided to define tasks and to set their memory 
allocations; tasks are activated by the word activate (Mach2) or 
activate< (MacForth), followed by the code the task is to 
execute. Task switching is initiated by calling PAUSE from 
within the task code. Some Mach2 and MacForth words (like 
input/output, GET and RELEASE) contain a PAUSE in their 
code; this is clearly documented in the glossaries. 

. In Mach2, a task can be automatically linked to a window and 
amenu bar; this greatly simplifies task handling. The Mach2 user 
variable area contains task-specific vectors, for example, for 
input/output or event handling, which may also be altered by 
other tasks. 

MacForth's multitasking system offers the advantage of being 
able to delay a task for a specified number of ticks. The variable 
delay is accomplished by a VBL task associated with each Forth 
task, which wakes up the Forth task after the delay has expired. 

In Mach2 one would still have to install such a feature, which 
shouldn't be very complicated; however, having it built in would 
make a useful addition. 


Editing 


For a long time, MacForth has forced users to stick with a 
block-style editor, almost like simple CP/M Forth systems. I 
suppose I'm not the only one who didn't understand why they 
wouldn't accept standard text files as an input. The main problem 
with the block files was that it was so complicated to insert things 
in the middle of a program that one was tempted to fill up the 
available block space to the limit of incomprehensibility of the 
code. 

Now, CSI seems to have got their act together and has provided 
the MacForth Plus user with a four-window (maximum) inte- 
grated editor, the source code of which is provided. It offers 
everything that a good standard program-text editor for the Mac 
should have, and in addition interesting goodies like display of 
page breaks in the text and a pop-up window to display file size 
and line numbers when using the vertical scroll bar. 

The MacForth Plus editor is an excellent product, and one can 
only hope that the editor that was promised with the Mach2 
system (Real Soon Now) is comparably good. One very impor- 
tant feature is that by selecting a range of text and pressing 
ENTER you can immediately execute the selection range (i.e. 
compile a definition or execute some code); the result of the 
execution is displayed in the edit window, thus becoming part of 
the edited text. Very much like the MPW worksheet windows and 
extremely useful. Of course, the old block style editor is still 
provided so that older MacForth code does not become useless. 

Mach2 does not yet offer an integrated editor. One either has 
to use the Transfer option on one of their menus to get into Edit 
(bypassing the Finder) or use a desk accessory editor such as 
miniWRITER or MockWrite. The editor task written by Juri 
Munkki (MT V2#11) is another possibility. Palo Alto shipping is 
sull working on the editor as I write this; I hope the Mach2 update 
with the editor will be available when you read my column. 


467 


Resources 


Resources that are used by your Forth code are kept in an extra 
file named resource.bag in MacForth Plus and MACH.RSRC 
in Mach2. That resource file will automatically be opened when 
the Forth system starts up, and the resources will be accessible by 
their types and IDs. 


Stand-alone applications 


Both systems include a TURNKEY feature that will generate 
a stand-alone application out of your Forth code. Mach2 will 
automatically copy ail resources from the MACH.RSRC file into 
the application. In MacForth, the user has control over which 
resources from the resource.bag file will be included in the final 
application; this is accomplished by a resource list which con- 
tains the handles of the resources to be copied. 

One last thing that must not be forgotten is that Mach2 is the 
only Forth system available for the Macintosh which allows you 
to program things other than applications in Forth, such as INIT 
routines, VBL tasks, desk accessories, etc. etc. It is even conceiv- 
able (and planned, as far as I know) to be able to link routines 
written in other languages to the Forth code and vice versa. 


Programming examples 


This is an important point. Nothing helps better to get used to 
a new development system than lots and lots of programming 
examples. Both Mach2 and MacForth offer a large variety, in fact 
they supplement each other; I often found useful concepts for one 
System in examples from the other one. It would be desirable to 
have more of Mach2's source code available, as MacForth has 
(NEON, too, is a master example of a well documented system 
Source). 


Conclusion 


I won't give a recommendation for a specific Forth system. If 
your main issue is speed, you might be better off with Mach2, 
especially if your code uses a lot of floating point calculations. 
Also, if you want to write a desk accessory or a window definition 
routine in Forth, Mach2 is the answer. 

MacForth seems somewhat more flexible in the way re- 
sources can be handled and has a very good built-in editor. Its 
assembler will definitely appeal to die-hard Forth purists who 
want to do everything the reverse Polish way. The trap support 
is good with both systems, Mach2 staying closer to Inside Mac. 

If you plan to develop a large project in Forth, I suggest getting 
both systems....if only for the examples. 


Next column I'll take up desk accessory programming again, 
with some useful tricks and caveats. 


Listing 1: Forth benchmarks used in this coluan 
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С Screen invert, Mach2 and Mac* version) 

only forth also assembler also sane 

50 1504 524288 + constant screenlow C Mac Plus) 
5472 constant screenwords 

Screenlow screenwords 4 * * constant screenhigh 


code 18 
поуе.1 (6,ай 
поуе.1 (ай),-(аб) 
rts 

end-code 

mach 


code i! 
поуе.1 d6,a@ 
поуе.1 Ca62*,Ca0) 
rts 

end-code 

nach 


code i* 
add. 1 
rts 

end-code 

mach 


d6, (86) 


code 3+ 
eddq. 1 
rts 
end-code 
nach 


t3, (a6) 


code center 
тоуе.1 d6,ad 
тоуе.1 (а0),-Саб) 
not.1 (аб) 
тоуе.1 (a6)+, (að) 
rts 

end-code 

mach 


: invert screenlow 
begin dup @ not over ! 4 + dup screenhigh = until drop ; 
: test counter 50 Ø do invert loop timer ; 


: invert2 screenhigh screenlow do i ё not i ! 4 *loop ; 
: test2 counter 50 9 do invert2 loop timer ; 


: invert3 screenhigh screenlow do i8 not i! 4 *loop ; 
: test3 counter 58 0 do invert3 loop timer ; 


: invert4 screenhigh screenlow do center 4 *loop ; 
: test4 counter 50 Ø do invert4 loop timer ; 


on 


screen inverter, definitions for MacForth, slightly altered 
) 
anew bench 
assemb ler 
501504 524288 + constant screenlow С Mac Plus) 
5472 constant screenwords 
screenlow screenwords 4 * + constant screenhigh 
: SHOW.TIME С ticks -- ) 

dup сг. 

." ticks : 

100 60 */ «88% ascii . hold 85 8> type 

" seconds" ; 

: counter tickcount ; 
: timer tickcount swep - show.time ; 


CODE bnot 
dð get, 00 long not, dð put, next 
END-CODE 


: invert! screenlow 
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begin dup @ bnot over ! 4 + dup screenhigh = until drop ; 
: test tickcount 58 Ø do invert! loop 
tickcount swap - show.time ; 


: invert2 screenhigh screenlow do i ё bnot i ! 4 *loop ; 
: test2 tickcount 58 0 do invert2 loop 
tickcount swap - show.time ; 


: invert3 screenhigh screenlow do i@ bnot i! 4 +loop ; 
: test3 tickcount 50 0 do invert3 loop 
tickcount swap - show.time ; 


: invert4 screenhigh screenlow 
do >С00Е 
d6 að long move, 
d5 að long adda, 
ай С) long not, 
>ҒОЕТН 
4 *loop 


д 
: test4 tickcount 
90 0 do invert4 loop tickcount swep - show.time ; 
( Eretosthenes Sieve Benchmark, stack version ) 
8192 constant size 
variable flags size vallot С ALLOT for MacForth Plus) 
: primes flags size 1 fill С empty array ) 
0 С prime counter ) size 0 С range ) 
do flags 1+ ce 
if 1 2х 3+ dup i+ size < ( avoid known nonprimes) 
if size flags + over i+ flags + 
do Ø ic! dup *loop С flick mod prime flags) 
then drop 1+ € another prime ) 
then 
loop 


: Sieve 10 0 do primes loop ; 
: Sieve.demo counter sieve3 timer ; 


( Eratosthenes Sieve Benchmark, local variable version ) 
: prime3 { | “primes prime*2:3 limit -- ) 
( note different syntax for MF+) 
( note also that i + should be replaced by i+ etc. in 
MF+ ) 
flags size 1 fill 
flags size + -> limit Ø -> "primes 


limit 1+ flags 
do i ce 
if i flags - 2* 3 + dup -> prime*2+3 
i + limit < 
if limit 1* prime*¥2+3 i + 
do Ø i c! prime*2*3 +loop С Bic! is one word in 
MF+ ) 
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then 
8primes 1+ -> “primes 
then 
loop 
“primes . ." primes “сг; 


: Sieve3 10 0 do prime3 loop ; 
: Sieve3.demo counter sieve3 timer ; 
: million.loops 

counter 1000000 0 DO LOOP timer ; 
( floating point benchmerks ) 
FP 


: fmerki рі 2.718281828e0 ." 10000 empty loops - " 
counter 10000 @ do fover fover fdrop fdrop loop timer 
fdrop fdrop ; 

: fmark2 pi 2.718281828e8 ." 10000 additions - " 
counter 10000 0 do fover fover f+ fdrop loop timer 
fdrop fdrop ; 

: fmerk3 pi 2.718281828e0 ." 10000 subtrections - " 
counter 10000 0 do Ғоуег fover f- fdrop loop timer 
fdrop fdrop ; 

: fmark4 рі 2.718281828e0 ." 10000 multiplications - " 
counter 10000 @ do fover fover f* fdrop loop timer 
fdrop fdrop ; 

: fmark5 pi 2.718281828e0 ." 10000 divisions - " 
counter 10000 0 do fover fover f/ fdrop loop timer 
fdrop fdrop ; 

: fmark6 2.718281828e0 ." 1008 square roots - " 
counter 1000 0 do fdup fsqrt fdrop loop timer 
fdrop ; 

: fmark? 2.718281828е0 ." 1000 sines - " 
counter 1000 0 do fdup fsin fdrop loop timer 
fdrop ; 

: fmark8 2.718281828e0 ." 1000 logarithms - " 
counter 1000 0 do fdup fin fdrop loop timer 
fdrop ; 

: fmark9 2.718281828e8 ." 1000 exponentiations - " 
counter 1000 0 do fdup Га1п fdrop loop timer 
fdrop ; 


: fspeed. test cr 
fmark1 cr 
fmark2 cr 
fmark3 cr 
fmark4 cr 
fmark5 cr 
fmark6 cr 
fmark7 cr 
fmark8 cr 
fmark9 cr 
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Forth Forum 


MACH 2 
Background Processing Under Switcher 


Switcher is the closest thing to a multiprocessing system on 
the Macintosh (not counting Servant, a fully functional version 
of which has not seen the light of day as I write this, or Finder 6.0 
which Apple is rumored to be developing). It is not really 
multiprocessing, since an application that is running in one 
partition of Switcher is put to sleep when you switch to another 
one. True multiprocessing is not easy to achieve on the Mac 
because it lacks memory management hardware (this, of course, 
has changed with the Mac П). 

Switcher does support some background processing, how- 
ever. The problem is that the application has to cooperate to allow 
background tasks to run. There is no way (no easy way, at least) 
that Switcher could interrupt a running application and transfer 
control to another one. It is the application itself that has to draw 
aclear line between foreground and background tasks, setting up 
pieces of its code to be run in the background that will by 
themselves transfer control back to Switcher. 

This is very similar to the way multiprocessing is achieved 
in the various Forth and Forth-based systems that you've been 
reading about in this column. In those systems, tasks have to be 
cooperative and transfer control back to the task switcher at 
convenient points in their code (through words like PAUSE in 
MacForth and Mach2). 

A Macintosh application under S witcher contains one inter- 
face point where control may be transferred to another task: the 
GetNextEvent routine. In fact, Switcher will only switch tasks on 
a call to GetNextEvent (when a switch request has been made). 

It is at this point where background processing can take 
place. Every time an application calls GetNextEvent, Switcher 
will not only check whether you clicked the mouse on the double 
arrow or issued a keyboard command to initiate switching, but 
also check whether any of the installed applications contain 
background tasks that have to be run while they are inactive. 

Such a background task routine may be a short piece of code 
that checks whether a character has come in from the serial port 
and stores it away in a file, or vice versa output from a file to a 
serial line. It may also run some ongoing calculations, collect 
data from an instrument, etc. It should return not too late after it 
has been called, in order not to cause too much slowing down of 
the active application. The backgound task will be part of an 
application installed under Switcher, where the task setup is done 


by the active part of the application and the task takes over when- 


the application becomes inactive. 

I'm sure none of you will be able to write a background task 
from these very general remarks. So how does one actually do it? 
A very useful document to read at this point is Inside Switcher 
(available through APDA). This document takes the same holis- 
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tic approach as Inside Macintosh in that it requires you to 
understand all of it before you can make sense of the first 
paragraph (or nearly so), but otherwise gives a very good account 
about the things to observe when writing applications that are to 
run under Switcher. 

First, lets look at the way task information is stored in 
Switcher. There is one global variable, SwitcherGlobals ($282), 
which contains a pointer to the beginning of the Switcher global 
variable area in the system heap. The structure of this area is 
described in Inside Switcher, and I'll shortly summarize it here. 

The example listing contains the definitions for the 
Switcher tables. Each application is contained in a designated 
piece of memory, called a world, which is pointed to by one of the 
world pointers at the beginning of the Switcher globals. An 
application's world starts with an 18-byte header, followed by the 
application stack and heap area. The last 32K of a world are 
reserved for use by Switcher. 


The header of a Switcher world contains in sequence: 

- PSRPtr, a handle to the process state record of the 
application (explained later), 

- a 2-byte flag field, 

- BkgdProc, a pointer to a background procedure. Each 
installed application may have one BkgdProc associated with it, 
and Switcher calls them in sequence whenever a null event is 
fetched from the event queue. If this pointer is NIL, nothing is 
executed. 

- SavScrBits, a handle to the part of memory that contains 
the saved screen bitmap of the application. If this is =0, the screen 
is not being saved. 

- DAPtr, a window pointer to a virtual desk accessory that 
the Switcher uses for Clipboard conversion. (This procedure is 
explained in Inside Switcher, and I won't go into details here). 


Soall we'll haveto dotoexecute a background routine under 
Switcher is to store a valid pointer to the routine in the BkgdProc 
field of the world header. Then Switcher will jump to that routine 
on each null event... and... probably come up with a beautiful 
bomb display unless the routine to execute is either extremely 
simple (such as RTS) or we have taken further precautions. 

Ideally, we'd like to write the background task in Forth and 
execute itin our Forth system's world. To do this, you need some 
interface to the Forth code that can be jumped to directly and 
returns via an RTS. In Масһ2, the Forth code itself has those 
properties, since it is subroutine threaded. In the case of Mac- 
Forth (for example), we'll have to store the address of the 
routine's code field in the BkgdProc field of the Switcher world, 
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and make sure the code returns via an RTS (and not through the 
Forth system's NEXT routine). The example program is in 
Mach2, but MacForth users will easily be able to adapt the code 
to their system following these principles. NEON users will have 
to define the background routine using :proc and ;proc, the 
words provided for defining routines whose addresses may be 
passed as parameters to toolbox traps. 

The problem with executing a background task written in 
Forth using the surrounding support of the Forth system is of 
course that all existing Forth systems depend heavily on a set of 
registers in which parameter stack, return stack, user area point- 
ers, loop indices, etc. are kept. The status of the registers, 
however, is completely undefined when Switcher calls the back- 
ground routine. Therefore, the simple approach described above 
must fail. 

In order to properly execute a background routine from 
outside, we have to do what is known as context switching, 
meaning that a) the register file has to be restored to the values 
used by the Forth system, and b) any system global variables that 
are used by the Forth system have to be restored as well. All this 
is done automatically by Switcher on switching applications, but 
not when calling a background task; that would be much too 
much overhead. 

The full context switching is effected by Switcher through 
the information stored in the process state record of the applica- 
tion. This table is pointed to by the handle PSRPtr mentioned 
above. Its first four bytes contain its total size, followed by a copy 
of many of the low-memory globals used by the application. The 
location of important ones among them is given in Listing 1. 
Notice that StkLowPt and HeapEnd are contained here, these 
variables being consulted by the 'stack sniffer' to determine 
whether to display a System Error 28. 

What interests us most here is that the last four bytes of the 
process state record contain the value of the stack pointer left 
behind when control was transferred to another application. The 
last thing saved on that stack before switching are registers AO- 
Аб and D0-D7, through a MOVEM.L A0-A6/DO-D7, -(A7). 

Therefore, restoring A7 to the value left behind and then 
popping the other registers off the stack will leave us with a 
register set equal to the one left behind on switching. But... trying 
to do so is almost certain to get you a number 28 bomb, because 
AT it totally out of line with the actual contents of StkLowPt and 
HeapEnd. There is an excellent chance that the stack sniffer will 
notice this and... bang. The method I chose in the glue routine for 
calling background procedures is to use AO as a temporary stack 
pointer and restore the registers from there. Since Ido not change 
StkLowPt and HeapEnd, А7 must stay the same as well, so the A7 
Stack of the calling application is used for the background 
routine. This really doesn't make a big difference, as long as your 
routine doesn't do funny things with JSR return addresses left on 
the stack. 

After the registers have been restored, of course, they're all 
valid for the context of the background task (including A5). 


How does a background task know which Switcher world it 
is contained in (we need to know this to find the process state 
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record and get the stack pointer)? Lets look at the example listing 
again at this point. I have provided a couple of words that are 
useful when running under Switcher. isSwitcher looks at the 
SwitcherGlobals pointer; if it is positive (i.e. the pointer is valid), 
Switcher is installed. Worlds will display the names of all 
installed applications. The way this is done is by looking at all of 
the eight world pointers, access the process state record for each 
application and display the string starting at PSR +344. This is 


 wherea copy of the system global AppName is kept. The general 


layout of the global variable space in the PSR can be seen from 
the listing; not all of the system globals are transferred on 
switching, but the variables for Quickdraw, Toolbox and the 
Segment Loader (starting at $800 in the 'real world’) are saved 
consecutively starting at PSR +72. 


ActiveWorld# displays the number of the world that the 
active application (Mach2, in this case) is currently running in. 
This routine gives interesting information, but is useless for code 
in a background routine to determine whether it is active or not 
(because we still don't know which application contains the 
background routine). Inside Switcher gives a recommendation: 
store the value of ApplZone (global $2A A) in variable space in 
your program when the application is initialized (storeAp- 
plZone does this), and later compare this saved value with the 
current value (IamActive is provided for this purpose). 


I hope you're well enough 'primed' with some aspects of 
Switcher now so that we may continue with the actual problem 
of the day, installation of a Forth-written background routine that 
performs some useful task. 

The routine that Switcher executes will be a glue routine that 
makes sure the register file is ok, calls the Forth routine that has 
to beexecuted, then restores the registers and returns to Switcher. 

Switcher passes one parameter to the background routine, 
the task's WorldPtr in register A1. The glue routine first deter- 
mines whether the application that contains the task is active or 
not. If the application is active, the process state record may be 
invalid (it is updated only when the application becomes inac- 
tive); therefore the actual background task will be skipped over 
in that case. 

If the application is inactive, the glue routine gets the 
PSRPir from the world header and restores the register file as 
described above. Then, control is passed to the background task. 
On retum, everything is restored. 

The background task in the example will opena text file and 
do a draft quality print (ASCII mode) on the Imagewriter. The 
program is adapted (rather heavily adapted) from an example 
given by Palo Alto Shipping on their demonstration disk. The 
original program was meant to print a file as a background task 
under Mach2, and therefore contained PAUSEs and async I/O 
calls. These features are not really needed here and have been 
removed. In fact, they're dangerous for what we are doing for the 
following reason: 

Itis not really possible to jump into the context of the Forth 
System by just restoring all registers and expecting everything 
else to behave. The problem is with the low memory system 
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globals, which would have to be updated, too. It seems that 
anything that contains a PAUSE will bomb. One of the reasons 
for that might be that transfer will be given to other Mach2 tasks 
that try to write to the screen, and that is a no-no for background 
tasks according to Inside Switcher. 

The other Forth routines, notably those which are called by 
offsetting from AS or going through a jump table, will execute 
normally from the background. Macintalk will bomb; anything 
that requires calls to the Segment Loader, probably, too (I haven't 
tried this). 

The printing routine, then, does the following: From the 
foreground, a file to print is selected. Then the background task 
is installed; when the application becomes inactive, it will start 
to read the file in 512-byte chunks and dump it on the printer. 
Meanwhile, you will be able to use other applications under 
Switcher. However: 512 byte blocks are really too large to make 
the other programs run smoothly. I haven't changed the block size 
in the example, but it is an easy matter to do so; it might even be 
better to transfer only one character on each call of the back- 
ground task. Anyway, the example does illustrate the point, and 
you'll be able to install other background processes this way (and/ 
or translate the whole thing to NEON or MacForth). 

After a file has been printed, the SFGetFile dialog comes up 
again (in the foreground), and you can select another one. 
Cancelling the dialog will remove the printing routine from the 
Switcher worlds. 


Concluding remarks 


There is a lot more to be said about Switcher: how to access 
one application's variables from another program, how to deal 
with VBL routines and asynchronous I/O, how to switch auto- 
matically from within a program, clipboard conversion, suspend/ 
resume events, etc. etc. But I cannot repeat Inside Switcher here, 
so I'd strongly suggest you to get acopy from APDA incase these 
subjects are of any interest to you. 

Last time I had promised to give some more hints about DA 
programming from Forth; we'll put that off for a later column. 

There is one last comment I have to make concerning the 
eternal MacForth vs. The Other Forths issue. I happen to use 
Mach2 for the examples in my column; this shouldn't be viewed 
as a bias on the part of MacTutor or myself for one particular 
system. It is just that I prefer to become familiar with one 
development system rather than trying to cover everything. I try 
to keep the Forth code quite generic, to facilitate translation into 
other dialects, or use assembler. Since (I hope) this column is also 
read by people who develop in other languages, it is also 
important to stay rather close to the toolbox, which Mach2 
happens to do. Combine this with an assembler syntax which 
conforms to the Motorola syntax, and the code should be easily 
translatable into C or Pascal as well. 

I realize that there are many of you readers out there who do 
a lot of development in other Forth dialects. As you know, I 
always welcome contributions by readers to add some variety to 
this column. So if you have an interesting example in MacForth, 
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Mach2, MasterForth or another Forth, or NEON, by all means 
write it up and send it to me (directly to my address given in the 
masthead). 

We're hoping to hear from you. Until next month, happy 
threading. 


Listing 1: Switcher background printing example 


С Forth background applications under Switcher ) 

( Feb 1987 J. Langowski / MacTutor ) 

( raw printing example adopted from Mach2 exemple disk ) 
( for background printing under Switcher ) 


only forth also assembler also mac 
HEX 


CONSTANT fsRdPerm € read-only) 
CONSTANT fsWrPerm € write-only) 
CONSTANT fsRdWrPermC read-write) 


1 

2 

3 

0 CONSTANT fsAtMark 

1 CONSTANT fsFromStart 
2 CONSTANT fsFromLEOF 
3 CONSTANT fsFromMark 
3 

0 

6 

А 


CONSTANT stdFile 
CONSTANT 


CONSTANT 
CONSTANT 


rGood 
rVolume 
rName 


C CONSTANT ioCompletion 
10 CONSTANT ioResult 

12 CONSTANT ioFileName 
16 CONSTANT ioVRefNum 
18 CONSTANT ioRefNum 

1A CONSTANT ioFileType 
1B CONSTANT ioPermssn 
1 CONSTANT ioMisc 

20 CONSTANT ioBuffer 

24 CONSTANT ioReqCount 
28 CONSTANT ioActCount 
2C CONSTANT ioPosMode 
2E CONSTANT ioPosOffset 


FFD9 CONSTANT PastEOF 
( error code -39. used in file read operations ) 


DECIMAL 
HEADER typeL ist 
DC.B 'ТЕХТ' 
HEADER sf ReplyA 
DC.B С good 2 
DC.B 0 ( сору р9.25 PackSF ) 
DC.B ‘TEXT ' ( {Туре 2 
DC.W 0 ( vRefNum 2 
DC.W 0 ( version ) 
DCB.B 64,0 ( {Мате [string 63) 2 
HEADERPor tBOut 
DC.B 5 
DC.B ' Bout’ 
( ==== Various Imagewriter commands ======= ) 
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С Top-0f-Form CTRL-L %с ) 

С Software Reset ESC C $18 $63 ) 

C LF's after CR's ESC D e CTRL-@ $18 $44 $80 $00 ) 
С No LF's after CR's ESC Z 6 CTRL-e $18. $5A $80 $00 ) 
( cancels all unprinted CTRL-X $18 ) 


HEADER AddLFs 


DC.B $18 
DC.B $44 
DC.B $80 
DC.B $00 
HEADER AddTabs 
DC.B $18 
DC.B $28 
DC.B '008,0 16,824 , 032,049,048, 056, 064' 
HEADER FormFeed 
DC.B $0C 
DECIMAL 
LABEL CRCounter 
DS.L 1 


LABEL LeavePr intFlag 
DS.W 1 


LABEL MyBuffer 
05.В 512 


LABEL FilePBlock 
DS.B 50 


LABEL PrintPBlock 
DS.B 50 


( These аге the old routines ) 
( given by Palo Alto Shipping in the Mach 2.0 examples. ) 
( Since it's all in assembler, we can be sure that no calls ) 


ere made to the multitasking system which would interfere ) 
with our background processing ) 


ex) 


( 2225 Get File Info ====== ) 
С Ask for the file to be converted) 


CODE GetFInfo 

MOVE.W #80, -САТ) 
MOVE.W 50, -САТ) 
CR.L -СА7) 
CR.L -САТ) 
MOVE.W %41,-САТ) 
РЕА typeList 
CLR.L -САТ) 


C where.h ) 
C where.v ) 
€ prompt not used ) 
С we don't need filter ) 
С look for 1 type ) 
С pointer to typeList ) 
С no digHook ) 
PEA sfReplyA С push address of reply record) 
MOVE.W 82,-CATD C for SFGetFile ) 
-Pack3 С call package ) 
LEA SfReplgA, AQ С Point to sfReply 2 
TST.B | rGood(CA0) CIf cancel was clicked, return) 
BEQ.S @2 


С Open the source file) 


LEA filePBlock,A1 
CLR.L ioCompletionCA1) 
PEA rNameCA2) 
MOVE.L CAT7)+, ioFileNemeCA1) 
С Store pointer in diskPBlock) 
MOVE.W  rVolumeCA2), ioVRef NumCA1) 
( Store vRefNum in diskPBlock) 
CLR.B = ioFileTgpe(ADD ( Must set file type = 0 ) 
MOVE.B — fsRdPerm, ioPermssn(A 1) 


( Point to parem block ) 
€ No completion routine ) 
С Point to file name ) 
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С Open for read only ) 
CLR.L ioMisc(A1)( Use system buffer ) 
MOVE.L А1,А0 С Аб points to diskPBlock ) 


- Open C Open the file ) 
TST.B 00 
BNE.S  e1 


MOVE.W 24(Ү0),22(А0) 

( move ioRefNum into position) 
( ioPosMode from beginning) 

С ioPosOffset of 0) 

C this will reset the file) 


MOVE.W #1, 44(CAQ) 
СЕЛ .— 46CA0) 
-SetFPos 
LEA CRCounter , Ad 
CLR.L CAB) 
RTS 
01 MOVE.W #],-(А7) 
-SysBEEP 
62 -ExitToShe11 
END-CODE 


С ***** Initialize Port В ***** ) 


CODE InitPortB С SerOpenBOut) 
LEA PrintPBlock, AQ С Head of PBBlock) 
CLR.L $CCA0) С No completion routine ) 
LEA PortBOut, A1 С ioNamePtr ) 
MOVE .L A1,$12CA0) 
MOVE.B "g $1BCA0) 
MOVE .W 8-0 $18CA0) 
-Open 


С Ask for 811 permission ) 
С ioRefNum ) 


( SerRstBOut) 
LEA PrintPBlock,A8 С Head of block ) 
MOVE.W 8-9,$18СА0) С ioRefNum ) 
MOVE.W — *$09008,$1ACA0) С Control number ) 
МОМЕ. м '$CC2A, $1CCA0) 
С 9600 Baud,8d,2s,no parity ) 


- Control 

С Conf igure) 
LEA Pr intPBlock, Аб 
CLR.L 12CA0) С ioCompletion 2 
LEA AddLFs, A1 
MOVE.L А1,32(А0) С ioBuffer ) 
MOVE.L 84, 36CA0) С ioReqCount ) 
Write 
LEA Pr intPBlock, Ай 
CLR.L 12CA0) ( ioCompletion ) 
LEA AddTabs, A! 
MOVE.L А1,32(А0) С ioBuffer 2 
MOVE.L 834 ,36CA0) С ioReqCount 2 
_Write 


С CirLeaveF lag) 
LEA 


LeavePrintF lag, Аб 
КЕЙ (A0) 
RTS 
END-CODE 
( ==== Read a block from the file ======= ) 


CODE ReadBlock 
LEA FilePBlock, Аб 
CLR.L 12(А0) 
(ҒА MyBuffer,A1 
MOVE.L A1,32CA0) С ioBuffer) 
MOVE.L 8512, 36CA0) С ioReqCount) 
CLR.W 44СА0) С ioPosMode, from current mark) 
-Read 


С ioCompletion) 


ез CMPI.L 
BEQ.S 


85 12,40CA0) ( ioActCount ) 
@2 
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LEA LeavePr intFlag,A1 IF € 5 call sysbeep 2 С for testing ) 


MOVE.W — S$FF,CAD ReadBlock ( read a block in from file ) 
62 RTS PutPageBreaks (С insert form feeds every 60 lines) 
END-CODE WriteBlockC write the block to port B ) 
THEN 


. 
М 


С **** globals 2 


С ***** Put in the page breaks ***** ) 


( Search thru MyBuffer for CR's -> %00. HEX 
In place of every 68th one, I will insert a %С, 282 CONSTANT SwitcherGlobals 
which, when sent to an Imagewriter, will generate a form 286 CONSTANT MemToSwitch 
feed. ) 2AA CONSTANT AppiZone 
910 CONSTANT CurApName 
CODE PutPageBreaks DECIMAL 
LEA FilePBlock,AQ 
MOVE.L 40СА02,00 € ioActCount 2 С **** Switcher globals ) 
LEA MyBuffer,A1 0 CONSTANT World® С pointer ) 
LEA CRCounter , Ad 4 CONSTANT Worldi € pointer ) 
CLR.L D1 8 CONSTANT World2 € pointer ) 
e1 CMPI.B #5#$00,0(А1,01) С carriage returns ) 12 CONSTANT World3 С pointer ) 
BEQ.S @2 16 CONSTANT World4 С pointer ) 
e3 ADDQ.L 8101 С increment address offset ) 20 CONSTANT World5 € pointer ) 
SUBQ.L 81,00 С decrement byte counter 2 24 CONSTANT World6 С pointer ) 
BNE.S e1 28 CONSTANT World? С pointer ) 
RTS С ***** this is the exit point *** ) 32 CONSTANT HostTask ( pointer ) 
36 CONSTANT TheTask ( pointer ) 
e2 ADDQ.L &1,СА0) 40 CONSTANT Flags ( word ) 
CMPI.L 260, (AQ) 50 CONSTANT ArrowEnable ( byte ) 
BNE.S e3 САҒ this is the 60th CR ) 51 CONSTANT ClipConvert С byte ) 
52 CONSTANT Hibernation С word ) 
MOVE.B %$0C,0CA1,D1) С then insert a FF char D 54 CONSTANT MainZone С pointer ) 
CLR.L (A0) С and reset the crcounter ) 58 CONSTANT CoreTable С 6 LongInts ) 
BRA.S e3 90 CONSTANT NextTask С pointer ) 
END-CODE 96 CONSTANT SwitcherName С Str255 ) 
( **** structure of a world ) 
С ***** Write out a block to port B ***** ) @ CONSTANT PSRPtr ( pointer to PSR ) 
4 CONSTANT WorldFlags С word ) 
CODE WriteBlock 6 CONSTANT BkgdProc ( pointer to background routine ) 
LEA PrintPBlock, Ад 10 CONSTANT SavScrBits С pointer to saved Screenbits 2 
CLR.L 12СА0) С ioCompletion) 14 CONSTANT DAPtr С pointer to virtual DA ) 
LEA MyBuffer,A1 18 CONSTANT StackHeap ( stack & heap starts here... ) 
MOVE.L A1,32CA0) ( ioBuffer) 
LEA FilePBlock,A1 ( **** Switcher process state record ) 
MOVE.L 40(A12,36CA0) 0 CONSTANT Size ( LongInt : PSR size ) 
С move ActCount into ReqCount) 4 CONSTANT myMonkey С word ) 
-Nrite 6 CONSTANT MemTop ( address of end of RAM for this process) 
RTS 10 CONSTANT BufPtr ( address of end of jump table 2 
END-CODE 14 CONSTANT StkLowPt ( lowest stack address ) 
18 CONSTANT HeapEnd € address of top of heap ) 
С ***** Feed the final form feed ***** ) 22 CONSTANT TheZone ( address of current heap zone ) 
26 CONSTANT AppliLimit С application heap limit 2 
CODE DoFormFeed 30 CONSTANT SEvtEnb ( 4 bytes ) 
LEA PrintPBlock, Аб 34 CONSTANT MyApplZone С application heap zone ) 
CLR.L 12CA0) С ioCompletion ) 38 CONSTANT MinStack 
LEA FormFeed,A1 72 CONSTANT GrafBegin 
MOVE.L A1,32CA0) С ioBuffer 2 332 CONSTANT MyA5 C hex 14C ) 
MOVE.L — 81,36CA0) С ioReqCount) 344 CONSTANT MyName 
Write 836 CONSTANT DefVCBPtr pointer to default VCB 2 
RTS 
END-CODE ( **** event record structure ) 
0 CONSTANT what ( Integer ) 
С ***** Close the file ***** ) 2 CONSTANT message С LongInt ) 
6 CONSTANT when ( LongInt ) 
CODE ClFile 10 CONSTANT where С Point 2 
(ҒА FilePBlock, Ag 14 CONSTANT modifiers € Integer ) 
CLR.L 12(А0) С ioCompletion) 
Close ( ioRefNum should still be there) VARIABLE thisApplZone ( for intermediate storage ) 
RTS 
END-CODE ( **** definitions ) 
С ***** Main Thing ***** ) ; =string ( aStr bStr | -- flag ) 
: Print.bkg aStr count 65536 * bStr count rot * swep 
LeavePrintFlag Wê 0- call CmpString 0- 
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: isSwitcher SwitcherGlobals 6 ® ; 


: Worlds ( | Sw61 -- ) 
SwitcherGlobals 8 -> SwG1 


5и61 0» 
IF 
8 9 DO 
I 4 * SwG] + ё ?dup С world * i non-NIL ? ) 


IF 

cr ." World No." 7. 0": " 
@ 6 MyNeme + count type 
THEN 


: ActiveWorld# ( | SwGl wn -- world number ) 
SwitcherGlobals 6 -> SwG] 
-1 -? wn 
561 0» 
IF 
8 0 DO 
I 4 * $46] + ё ?dup С world 8 i non-NIL 2) 
IF 
6 ё MyApplZone + 6 ApplZone ё = 
IF I -> wn leave THEN 
THEN 


; 
С this routine should be called immediately after launch ) 


С or in апу cese before а background routine is installed ) 
: StoreApplZone ApplZone 6 thisApplZone ! ; 


: IemActive thisApplZone @ ApplZone 6 = ; 
HEADER tempA7 DC.L 0 

HEADER myWorld DC.L 0 

HEADER myPSRPtr DC.L 0 


CODE Bkg.glue 


MOVE .W SR, -CA7) 
MOVEM.L 00-07/Аб-Аб, - CAT) 
LEA tempA7, Ad 
MOVE .L AT, CAB) 
LEA myWorld, Аб 
MOVE.L A1, CAB) 
MOVE.L CA1),A1 С PSRPtr -> A1 ) 
LEA nyPSRPtr, AQ 
MOVE.L (A12,CA0) 
LEA SwitcherGlobals, Аб 
MOVE.L CAB), AD 
CMPA.L {ћеТаѕкСАб ),А1 
BEQ.S 61 

( we're active, so don't execute background ) 
MOVE.L (A12,A1 € start of PSR ) 
MOVE.L (А12,А0 С size of PSR ) 
ADDA .L A1,A0 
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SUBQ.L 84,A0 Cleft stack pointer behind here) 


MOVE.L CAB), A0 
MOVEM.L CAG )+ ,DØ-D7 /Аб-Аб 
( restore MACH2 register set, except AT ) 
LEA nyPSRP tr ; Аб 
MOVE.L CAB), Al 


( just in case the background routine needs it ) 


JSR print.bkg 


61 LEA tempA7, AG 
MOVE.L CAB), AT 
MOVEM.L CAT )+, DO-D7 /Ай-Аб 
MOVE.W CA7)+, SR 
RTS 


END-CODE MACH 


1000 6009 BACKGROUND printer 


: initBkg 
IemActive IF 
GetFInfo € open file to print, exit if cancel ) 
['] Bkg.Glue 
SwitcherGlobals @ ActiveWorld 4 * + e 
BkgdProc * 
| 


InitPortB 
THEN 


: rmvBkg 
TamActive IF 
0 


SwitcherGlobals 0 ActiveWorld#® 4 х + @ 
BkgdProc + 

| 

THEN 


: бізгіле 
storeapp1zone 
BEGI 
initbkg 
BEGIN PAUSE LeevePrintFlag wë UNTIL 
rmvbkg 
AGAIN 
д 


: backgo ACTIVATE startme ; 


: main printer BUILD 
printer backgo 


4 


( turnkey main backprint 
would now create the background printing application. ) 
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Toolbox Techniques 


PICT to RMaker Source in MacForth 


This program illustrates calling traps, using dialog boxes, 
the desk scrap, and the memory manager from MacFORTH. It 
takes a picture from the clipboard and converts it to RMaker 
resource format. The converted picture is put back into the desk 
scrap, So you can paste it into your resource file, using MockW- 
rite or other editor. 

Dialog boxes make programs more Mac-like and more 
"attractive", but they can be a bit tricky in MacFORTH. The 
reason is that the MacFORTH window always executes an 
ABORT when it is activated, and itis always activated when the 
dialog box is erased, if it was active before the dialog was drawn 
(To see what else is done when the MacFORTH window is 
activated, try SYS. WINDOW +ON.ACTIVATE W@. Use the 
forth decompiler from MacTutor Vol 1,42 to decompile this 
token). For example, you start your program that calls a modal 
dialog box by typing the highest-level word in the MacFORTH 
window. When the dialog box is drawn іп front, the MacFORTH 
window is de-activated. When the dialog is disposed of, the 
MacFORTH window is automatically activated and your pro- 
gram is aborted. This program works because all processing is 
done, before the dialog box is disposed of. 

A couple of words in the program are from Thinking Forth: 


: V OIN e 3С0 AND C/L + DIN! ; 
line) 

: ASCII BL WORD 1+ C@ COMPILING IF [COMPILE] LITERAL THEN ; 
IMMEDIATE (Cleaves ascii value of following character on 
stack, or compiles it as a literal if used within a defini- 
tion) 


IMMEDIATE (skips rest of 


I also used one naming convention from Thinking Forth. 
Word names starting with "/" imply "bytes per", so /Row means 
bytes per row. I also tried to use descriptive names and ample 
comments. Forth can be hard to decipher, but doesn't have to be. 

MacFORTH provides several pre-defined words for defin- 
ing your own trap-calling words. What they do is compile 
machine code into your definitions that formats the stack for you, 
such as converting items that are supposed to be integers from the 
32 bits that MacFORTH uses for everything, to 16 bits, or taking 
all of the arguments off the stack, reserving space for a returned 
result, then putting the arguments back on the stack. They also 
compile the trap code into the word. 

These pre-defined words are listed in table 1 along with the 
argument patterns they work for. Since the "FUNC" words must 
reserve space on the stack for a returned value underneath the 
arguments, they are for very specific casesonly; the "MT" words 
are more general. For example, W2MT may be used with a trap 
that needs one 16-bit item on top of any number of 32-bit items, 
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520 Larry Tannenbaum 
Long Beach, CA 
MacTutor Vol. 3 No. 5 


Picture Resources 


Resource ID# [on | 


Picture Bytes 245 


Picture Width 40 


Picture Height 32 


Larry wrote E 
this program! 


Fig. 1 Pict to RMaker source Dialog Box 


but W>FUNC>L must be used with a trap that takes one 16-bit 
argument only. If the trap you want to use doesn't fit any of these 
patterns, you must format the stack yourself and use MT for your 
definition. 

Blocks 1 to 4 contain examples of calling traps from 
MacFORTH. The word W Adj, in Block 1, converts 32-bit items 
to 16 bits; it adds 2 to the stack pointer, essentially chopping off 
the two most significant bytes of the top stack item. I couldn't get 
OPEN.RSRC, supplied by MacFORTH 1.2 К2.3, to work, so I 
defined my own word, OpenRFile, to do the job. The 2nd line 
of code in block 2 is executed while the file is loading. It takes 
the name of the loading file as the resource file name. This way, 
if you rename the file, the resource fork will be opened properly 
without changing the code. 

How do you get resources into a block's file? First, compile 
the resources with RMaker. The type and creator of the output 
file should be BLKS MATH. Go to MacFORTH and open the 
new resource file with OPEN" rfilename". You have just 
opened the empty data fork of the file. Append enough blocks to 
it to hold the program (APPEND.BLOCKS). Either type in the 
program, or use XFER.BLOCKS (block 12 of Forth Blocks) to 
transfer it from another block's file. It's easier to use separate 
resource and blocks files, when developing a program. Finally, 
change the name of your completed file, because RMaker will 
delete it, if you recompile the resources. 

Idecided to use the desk scrap for the input and output of this 
program so that I could paste the picture resource into the middle 
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Defining Word Arguments Val 


MT All 32 bits 
WsMT One 16-bit 
2W>MT Two 16-bit 
FUNC»W None 
FUNCsL None 
W>sFUNCsL One 16-bit 
L>FUNC>W One 32-bit 
L>FUNCsL One 32-bit 


None 
None 
None 
One 16-bit 
One 32-bit 
One 32-bit 
One 16-bit 
One 32-bit 


OS.TRAP 


32-bit item put into AO before trap call 
Result code put into variable IO-RESULT 


of an existing file. It's also easy to select a portion of a picture 
with Paint Grabber or similar desk accessory and retrieve it from 
the desk scrap using GET.SCRAP. 

GET.SCRAP copies the scrap data to a handle that you pass 
toit. The handle is automatically sized, so it can be any length, 
including zero. You must also specify the type of data you are 
looking for. The most common types are text and pictures. Use 
the constant "TEXT or "PICT to designate the type you want. 
If the data in the scrap is different from the type you asked for, 
error code -102 is returned. An error code of zero indicates no 
error. 

PUT.SCRAP works similarly. Give it the address and 
length of the data, and the data type. It will copy your data to the 
end of the desk scrap and return a result code. 

ZERO.SCRAP deletes all data in the desk scrap and sets 
the scrap length to zero. You must execute ZERO.SCRAP before 
the first time you execute PUT.SCRAP, and before putting data 
into the scrap of the same type that is already there. This last 
restriction is necessary because GET.SCRAP always returns the 
first block of data of the type requested. If more than one chunk 
of data of a particular type is in the scrap, only the first one that 
was written is accessible. 

Two other words help conserve memory: LOAD.SCRAP 
and UNLOAD.SCRAP. UNLOAD.SCRAP writes the desk 
scrap to the clipboard file on disk, releasing the memory used by 
the scrap. LOAD.SCRAP "knows" whether the scrap data is on 
disk or not and reads it into memory, if necessary. GET.SCRAP 
apparently will not get the data from the disk, even though Inside 
Macintosh says it will, socall LOAD.SCRAP first, if there is the 
possibility of it being in the clipboard file. 

SCRAP.HANDLE returns the address where the handle to 
the desk scrap is stored. SCRAP.COUNTER retums the num- 
ber of times the scrap has been zeroed since system start-up. 
According to Inside Macintosh, you can check to see if this value 
has changed during the operation of a desk accessory. If so, the 
accessory has probably put some data into the scrap. 

SCRAP.LEN returns the address containing the length of 
the scrap data. This length includes 8 bytes for the scrap header. 
Sometimes the scrap is 8 bytes longer than the picture length, and 
sometimes it is 9 bytes longer. I suspect this has to do with 
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whether the picture size is odd or even. The program needs the 
length of the picture. The easiest way to get it is from the first two 
bytes of the picture itself, so I don't use SCRAP.LEN. Block 8 
contains the definitions using the scrap interface words. 

Block 5 holds the memory manager interface definitions. 
Many programs in MacTutor have dealt with getting, releasing, 
resizing, locking, and unlocking handles, so I won't go into detail. 
The MacFORTH words that do these things have explicit names, 
except maybe FROM.HEAP, which gets a handle, and 
TO.HEAP, which releases one. 

The program uses only one handle. GET.SCRAP copies the 
picture into it, then the handle is resized to hold the ascii. To 
avoid overwriting the data, the program starts converting from 
the end of the picture. 

Blocks 9 and 10 contain the code that actually does the 
conversion. The constant /Row, in block 9, determines how 
many bytes of the picture are represented on each row of text. It 
can be changed to any convenient value. 

Using this program, you can personalize your dialog and 
alert boxes, and keep the pictures in your source, rather than 
having to paste them in after compilation with ResEdit. The 
output format could also be changed to MDS or MacASM. 


С Block 0 


**XXXkkkxkXInstructiong**txxxxxxix У 


To use this program: 

1. Cut or copy picture to be used as resource so it will 
be in the ClipBoard. 

2. Load this file. 

3. Execute Pict>»Rsrc. The РІСТ in the clipboard 
will be converted to type TEXT in RMaker hex format. 

4. Using MockWrite or other editor, paste the data from 
the clipboard into the RMaker file. 


( Block $1 
HEX 


XXX xxxxxxx**Toolbox interface*****xtxxxxxx) 


Create WAdj -2 Allot 548F ( ADDQ.L 82,5Р) W, 4Е04 W, 


A997 L»FUNO ^W «OpenRF ile» 
А9ТС MT «GetNewD1og? 

A98D MT <GetDI tem 

А990 MT «GetIText? 

A95F MT «SetCTitle» 

A987 MT «NoteAlert? 


A99A WMT <CloseRFile> 
A983 MT «DisposDlog? 

А991 MT <ModalDlog> 

A98F MT «SetIText? 

A95D WMT <HiliteControl> 


DEC IMAL 

2 11 Thru 
с Block 82  **x****ToolBox InterfaceVar iablest*****2x% ) 
Create RFileName 38 Allot \ same name as this file 


Block-File @ @File.Name 
Variable RFileRefNum 
Variable DlogPtr 

Create ItemHit 2 Allot 
Create ItemType 2 Allot 
Variable ItemHandle 


Dup C@ 1+ RFileName Swap CMove 
\ returned by OpenRFile 
\ returned by GetNewDlog 
\ returned by ModalDlog 
\ returned by GetDI tem 
\ returned by GetDI tem 


Create — ItemRect 8 Allot \ returned by GetDI tem 
Create — Item$ 30 Allot \ for manipulating text items 
Create — Ok$ ," Done" V new title for control 


1 Constant ConvertButton \ compared to ItemHit when 


X Модг10109 returns 


( Block 83 XEXKKEXEXKKKRESOUrCE File/Alert**xxxtxxxxxx) 
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: OpenRFile RFileName «OpenRFile» Dup 0» 
If  RFileRefNum ! 
Else Abort" Couldn't open resource file!" Then ; 
: CloseRFile RFileRefNum 6 <CloseRFile> ; 
: NoPictAlert 128 WAdj С id) 0 С filter proc) «NoteAlert? ; 


(Block $4 — sxxexexeixsDialog Interface*trrrkixrkk) 


: GetDlog @ ( reserve stack space for returned dptr) 
128 WAdj С id) 0 С on heap) -1 € in front) 
«GetNewD10og? DlogPtr ! ; 

: DisposeDlog DlogPtr 6 «DisposDlog? ; 

: Мода10109 Ø C filter proc) ItemHit «ModalDlog? ; 

: GetDI tem ( item") DlogPtr @ Swap WAdj 
ItemType ItemHendle ItemRect <GetDItem ; 

: GetIHandle С item*--handle) GetDItem ItemHandle @ ; 

: GetIText (С $\item*) — GetIHandle Swap <GetIText> ; 

: SetIText (С item!) — GetIHandle Item$ «SetIText? ; 

: Ok»Done 1 С item) GetIHandle Ok$ «SetCTitle» ; 

: Can'tCancel 2 С item?) GetIHandle 255 <HiliteControl> ; 


( Block 85 xx*k*ikrk*iMemory Manager***itrxxxix) 
Variable DataH \ holds handle to data 


: GetH С size--hendle) From.Heap бир DataH ! Dup 0- 
If DisposeDlog CloseRFile 
1 Abort" Handle Allocation Error!" Then ; 
: DataPtr € --ad of data) DataH ёё Mask .Handle ; 
: /Dete С --data size in bytes) DataH @ Handle.Size ; 
: ResizeH ( new size--) DataH ё Dup Rot Resize .Handle 
@‹ If DisposeDlog CloseRFile 
1 Abort" Handle Resize Error!" 
Else Lock.Handle Then ; 
: ReleaseH 
/Data Ø< Not If DateH 6 Dup Unlock.Hendle To.Heap Then ; 


(Block 86  ***xxs5*35*P[CT Resource Header **Xxxxxxxx) 


13 Constant CRet \ ascii for carriage return 

: AddCR С ad--) Count 1- + CRet Swap C! ; 

\ Asterisk in string is place holder for carriage return 

Create Type$ ," TYPE PICT = GNRL*" Type$ AddCR 

Create Hex$ ," .H*" Hex$ AddCR 

Create Name$ 25 Allot 

Create 109$ 10 Allot 

: /Header С --n) Туре$ Ce Hex$ C@ Name$ Ce ID*$ СӨ + + + ; 

: (Header) Text) € ptr\$--updated ptr) 

Count >R Over Ré CMove R> +, 

: !Header DataPtr Type$ (Header? Text) 
Name$ (Header> Text) Id®$ (Неадег› Text) 
Hex$ (Header>Text) Drop ; 


С Block 87 5#51*55*5*%5*%Се{/5е{ Dialog I temst***eeexexk ) 


: NumStr Сп) «8 8S 4) [tem$ 2Dup C! 1% Swap Cmove ; 
: AddChar С $\char) Over Count + C! Dup C@ 1+ Swap C! ; 

: SetPictSize DataPtr W@ NumStr 9 SetIText ; 

: SetPictWidth 


DataPtr Dup 8+ W@ Swap 4+ W@ - NumStr 11 SetIText ; 
: SetPictHeight 

DataPtr Dup 6+ W@ Swap 2+ W@ - Num Str 13 SetIText ; 
: GetPictName Мате$ Dup 5 GetIText Ascii , AddChar ; 
: GetPictID® 109% Dup 7 GetIText CRet AddChar ; 
: GetHeader GetPictName GetPictID* ; 


: SetUpDlog 
GetDlog SetPictSize SetPictWidth SetPictHeight ModalDlog ; 
: DoneDlog Ok»Done Can'tCancel ModalDlog ; 


( Block 88 жжжжжжжжжжх]еѕк Scrap Interface*txxxxxexxkx) 


: ScrepErr? С result code--) 
Ø< IF ReleaseH DisposeDlog CloseRfile 
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1 Abort" Screp Error!" Then ; 

: /Pict С --bytes) 

Scrap.Handle 8 Dup Ø< If Drop Ø Else 6 4+ 6 Then ; 
: PictFromScrap С --result code) Load.Scrap ScrapErr? 

/Pict GetH "PICT Get.Scrap ; 
: Text>Scrap Zero.Scrap ScrapErr? 

DataPtr /Data “TEXT Put.Scrap ScrapErr? 

ReleaseH Unload.Screp ScrapErr? ; 


( Block 89 x*xxxx***XxxxPicture conversion*XXxXxxkkxxx) 


16 Constant /Row \ 1 row of text represents 16 bytes of pict 
: SCR'S C pict size--" of CR's in text ) 
/Row W/Mod Swap If 1+ Then ; 
: /Text С --text size) /Pict Dup 2% Swap ®CR'S + /Header +, 
: PictEnd € --ad) DataPtr /Pict + 1- ; 
: TextEnd € --ad) DataPtr /Text + 1- ; 
Create Char$ ," 123456789ABCDEF " Ascii 0 Char$ C! 
: Ascii С nybble--char) Сһагӱ + Ce ; 
: IByte С ad\byte--new ad) Dup>»R 15 And >Ascii Over C! 1- 
R> 16/ Ascii Over C! 1- ; 
(г ( ad--new ad) CRet Over C! 1- ; 


С Block 81g — **xxxxxxxxxpicture conversion****xxxxxxx) 
Variable PictAd 


: RowLimits С *ibytes--limitVindex) 

PictAd @ Dup Rot - Dup PictAd ! 1+ Swap ; 
: !Row ( dest ad\*bytes--new dest ad) 

RowLimits Do IC@ !Byte -1 +Loop ; 
: IPict PictEnd PictAd ! TextEnd 

| /Pict Do !Cr I /Row Min !Row /Row Negate *Loop Drop ; 
: Pic Text Watch Set.Cursor GetHeader 

/Text ResizeH IPict !Header Init.Cursor ; 


€ Block 811 KKKKKXEKKEK Ser Interface****kxxxxxx) 


: Convert? — ItemHit We ConvertButton = If 
Pico Text Text»Scrap DoneDlog Then ; 
: ConvertPict SetUpDlog Convert? DisposeDlog ; 
: Pic Rsrc OpenRF ile PictFromScrap 
Ø< If NoPictAlert 
Else Conver tPict 
Then CloseRFile ; 


Clip Region Can Get Ya 
Clifford Story 
Murfreesboro, TN 

Every morning when I get up, I kneel on a small rug and bow 
towards Placentia. Well,that's not true, but close! 

I wanted to draw a view of a picture in a window, and scroll 
it around so I could look at all of it. But whenever I moved it, it 
would disappear! I spent several frustrating hours with this 
problem, then turned to the stack of MacTutor back issues (I have 
bought them all...) There in the April 1986 issue, was an article 
by Chris Derossi, "On the Nature of Pictures", with a complete 
solution to the problem. It turns out that it was caused by the clip 
region- I would never have thought of that. MacTutor is just 
splendid. [Chris Derossi now works for Apple Computer, along 
with a host of other MacTutor authors! -Ed] 
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Forth Forum 


Multi-Window Stick Around DA мАСН 2 


"Multi-window, multi-menu, permanent 
desk accessory" 


As mentioned in a previous column, we are going to learn 
some more about creating desk accessories in Forth (Mach2) this 
time. The simple desk accessory from V3#2 was useful to show 
the principle of implementing such a thing in Forth, but in real life 
DA writing there are a number of things that one might have to 
add to that example. Therefore, I am going to write this time about 
the implementation of a desk accessory that supports multiple 
windows and menus; also it will automatically reinstall itself 
after it has been closed involuntarily (e.g. when calling an 
application from the Finder). 

This article is by no means comprehensive; there have been 
several articles in our journal on desk accessories implemented 
in assembler or C (V2#3,4,6), and I’m making use of some of the 
ideas described therein. So go back to those old issues (if you 
don't have them, order them through us) for any further refer- 
ences. 

Making a DA permanent 


As you'll certainly have noticed, there are several occasions 
when desk accessories will be closed automatically by the 
system. Whenever you start up a new application from the 
Finder, or quit an application to go back to the Finder, the 
application heap will be reinitialized and all desk accessories 
closed. The two other occasions on which your DA will be closed 
are copying a file under the Finder and ejecting the startup disk. 

Sometimes one would like to have a desk accessory (like a 
clock) stay active permanently, unless one closes it voluntarily. 
PI tell you further down below how that can be accomplished; 
however notice that in such a case one would always have to 
check whether the close box has really been clicked when the 
DA's Close routine is called. This is not so easy... since the 
system handles part of the mouse-down events for a DA auto- 
matically before we could even intercept them. Particularly, a 
mouse-down in the drag region will let the window be dragged 
around and a click in the Close box will generally cause the Close 
routine to be called. 

Soour first problem would be to distinguish a voluntary close 
from an involuntary one. One easy way to do this is to create the 
window withouta close box and let the user click a button inside 
it, or select some menu option, to notify the DA that we don't 
want itany more. The control - or menu - handling routine would 
then by itself call CloseDeskAcc but set a flag that indicates to the 
close routine that we really want to close the window. The close 
routine then had a way to distinguish voluntary from involuntary 
close through the flag. 


© The Essential MacTutor, Vol. 3 


Jórge Langowski 
MacTutor Editorial Board 
Grenoble, France 
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Fig. 1 DA sticks around between applications 


There is, however, a more elegant way to go. As was already 
pointed out by David Dunham in V2#6, there is a system global 
(undocumented in IM) called CloseOrnHook ($A88). If this 
location contains a non-NIL pointer, the system assumes that it 
is the address of a routine that should be called when the close box 
of a desk accessory window is clicked (instead of calling its Close 
routine). So all we have to do is to install a pointer to our own 
Close routine here every time the desk accessory window is 
activated and remove it when it is deactivated (so that other DAs 
may be closed correctly). The custom Close routine would then 
set the flag mentioned above and call CloseDeskAcc with the 
driver ID number of our DA. 


Hooking Into SystemTask 


Now that our Close routine knows whether we really wanted 
to call it or not, how do we go about making the desk accessory 
permanent? After all, the heap will be cleaned on starting up an 
application, and we won’t be able to keep our DA in the 
application heap even if we wanted. Even if we put it into the 
system heap instead, it will stay there - eating up memory - but 
receive no more system calls, so it will be unusable. 

Here a clever trick comes in that I again got to know on one 
of our developer’s club meetings (idea by L. de Bersuder): Since 
every application will call SystemTask pretty soon after having 
been started up, just install a patch (located in the system heap) 
to the SystemTask routine that reopens the desk accessory, then 
resets the old SystemTask trap address and thereafter removes 
itself from the system heap. This method, of course, will work for 
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one such permanent DÀ at a time only, but provides a good 
starting point from which on one can do further experimentation. 

Itis time, now, to look at the program. Listing 1 just contains 
general Forth definitions that are necessary for the program (and 
haven't changed much compared to the V3#2 column). Listing 3 
is the RMaker input for generating the desk accessory, and 
Listing 2 is our example. 

The code for the SystemTask intercept routine is at the 
beginning of the listing. The actual intercept routine does nothing 
but check whether there is a dialog present in front (in case our 
DA will set up a dialog as well, this can lead to conflicts), and if 
that is not the case, restores the old trap address for SystemTask, 
then opens the desk accessory, using a built-in name string. If you 
change the name of the accessory, you would have to change this 
string accordingly. The intercept routine is called by a glue 
routine which saves the registers and sets up a local A6 stack for 
the Forth code (our usual method); then the Forth code is entered. 
The Forth word write-out writes the code for the patch routine 
toa PROC resource (marked locked, in system heap, and with an 
ID of -16000, so that it belongs to the desk accessory). 

Installation of the SystemTask patch is performed in the 
Close routine. Here the flag closeflag is checked; if it is =1, it 
is assumed that the close was involuntary and the patch is 
installed by calling install.intercept. The latter routine gets 
the PROC resource containing the patch code (it will be in the 
system heap), stores the old trap address of SystemTask in 
trapaddr in the patch routine and sets the new trap address to the 
beginning of the intercept routine. The appropriate offsets 
*trapaddr and *inter have been calculated beforehand at 
compilation time. This, by the way, is one simple method to 
reference Forth code from outside routines. 

After the installation of the intercept routine, the system is set 
up to reinstall the desk accessory the next time SystemTask gets 
a call. 


Multiple windows and the custom Close routine 


To close the desk accessory for good, we make use of the 
CloseOrnHook system global. Both windows belonging to the 
DA carry the driver reference number in their WindowKind 
fields; so the system would normally handle close box clicks for 
them. To avoid this, we have to put a non-zero value into 
CloseOrnHook. Since a) we might want to install a different 
behavior for the close boxes depending which window is closed, 
and b) we need a custom close routine anyway to disable the 
automatic reinstallation, we install a pointer to the realclose 
routine in CloseOrnHook every time one of the DA windows is 
activated and reset that location to zero when it is deactivated. 

The routine pointed to by CloseOrnHook receives two para- 
meters: the dCüEntry pointer іп Al and the window pointer in 
A4. The window pointer is used to determine the action (one 
window will beep, the other one will close the DA for good when 
it is closed), and dCtlEntry is needed to determine the DA's 
driver reference number so that we can close it. 
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Multiple Menus 


This is only a little more involving than having just a single 
menu. In order to have the system pass the menu parameters to 
the DA for one out of several menus, we have to install the DA's 
driver reference number in the global MBarEnable ($A20, 
word). Then, when a window is activated, we get the handle of 
the current menu bar and save it away, and set up the menu bar 
using our own list of menus. In our case, I added two menus 
which will show up when the main window is clicked. When that 
window is deactivated, we reset the old menu bar from the stored 
value and set MBarEnable to zero. As long as MBarEnable is 
<>0, the DA will receive the menu ID in csParam and the menu 
item number in csParam + 2. This is taken care of in the СП 
routine. Our menu handler again simply displays the names of the 
items. 


Other remarks 


The zoom box and grow box are handled differently in this 
DA than they were in my first example (I briefly mentioned this 
in the March column). When a mouse down event is detected, we 
setthe windowKind field of the window record to 8 (application- 
created window) before calling FindWindow again, this time 
receiving the correct part code from FindWindow. The win- 
dowKind is reset to the old value thereafter, so that close box and 
drag region clicks will again be handled correctly by the system. 

Knowing the zoom box or grow box part code, we can then 
go and take the appropriate actions. 

Just for fun, I added a button in the main (resizeable) window 
which will show or hide the other window. That window displays 
the time. 


Happy threading and see you next month. 


Listing 1: Some general definitions for Масһ2 DA 
( € J. Langowski/MacTutor March 1987 ) 


HEX 

44525652 CONSTANT “drvr 
50524F43 CONSTANT “proc 
434E544C CONSTANT “cntl 


( *** System globals *** ) 
HEX 
8FC CONSTANT JioDone 


DECIMAL 
€ windowrecord fields, starting with grefport 2 
16 CONSTANT portRect С Grafport rectangle ) 


( fields of WindowPeek ) 
108 CONSTANT windowKind 
110 CONSTANT wVisible 
111 CONSTANT wHiLited 
112 CONSTANT goAwayF lag 
113 CONSTANT spareFlag 
130 CONSTANT dataHandle 
140 CONSTANT controlList 
152 CONSTANT refCon 


С fields of device control entry 2 
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4 CONSTANT dCt Flags 

6 CONSTANT dCtlQHdr 

16 CONSTANT dCtlPosition 
20 CONSTANT dCtlStorage 
24 CONSTANT dCtlRefNum 
26 CONSTANT dCtlCurTicks 
38 CONSTANT dCtlWindow 
34 CONSTANT dCtlDelay 

36 CONSTANT dCtlEMask 

38 CONSTANT dCtlMenu 


С csCodes for Ctl calls 2 
-1 CONSTANT goodBye 
64 CONSTANT accEvent 
65 CONSTANT accRun 

66 CONSTANT accCursor 
67 CONSTANT accMenu 
68 CONSTANT accUndo 
10 CONSTANT accCut 

Т1 CONSTANT accCopy 
72 CONSTANT accPaste 
73 CONSTANT accClear 


( *** standard parameter block data structure *** ) 

Ø CONSTANT qLink С pointer to next queue entry [long word] ) 
4 CONSTANT qType € queue type [word] ) 

6 CONSTANT ioTrap С routine trap [word] ) 

8 CONSTANT ioCmdAddr С routine address [long word] ) 

12 CONSTANT ioCompletion С completion routine [long word] ) 
16 CONSTANT ioResult С result code returned here [word] ) 
18 CONSTANT ioNamePtr С pointer to file name (long word] ) 
22 CONSTANT ioVRefNum € volume reference number ) 

24 CONSTANT ioRefNum 

26 CONSTANT csCode С type of control call ) 

28 CONSTANT csPeram( control call parameters ) 


( *** eventrecord data structure *** ) 
0 CONSTANT what 

2 CONSTANT message 

6 CONSTANT when 

10 CONSTANT where 

14 CONSTANT modifiers 


( *** eyent codes *** ) 
Ø CONSTANT null-evt 

1 CONSTANT mousedn-evt 
2 CONSTANT mouseup-evt 
З CONSTANT keydn-evt 

4 CONSTANT keyup-evt 

9 CONSTANT autokey-evt 
6 CONSTANT update-evt 
7 CONSTANT disk-evt 

8 CONSTANT activate-evt 
10 CONSTANT network-evt 
11 CONSTANT driver-evt 


0 CONSTANT inDesk 

1 CONSTANT inMenuBar 
2 CONSTANT inSysWindow 
3 CONSTANT inContent 

4 CONSTANT inDrag 

5 CONSTANT inGrow 

6 CONSTANT inGoAway 

1 CONSTANT inZoomIn 

8 CONSTANT inZoomOut 


CODE sh! € data “bits ) 
MOVE.L (A6)*,00 
MOVE.L (A62,D1 
LSL.L 00,01 
MOVE.L D1,(A6) 


T 
END-CODE MACH 
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CODE shr С data "bits ) 
MOVE.L CA6)+,D8 
MOVE.L CA6),D1 


LSR.L 00,01 
MOVE.L D1,CA6) 
RTS 


END-CODE MACH 


CODE on 
MOVEQ.L ** 1,D0 
MOVE.L (CA6)+, Ad 
MOVE.L 00, CAB) 
RTS 

END-CODE MACH 


CODE off 
MOVE.L CA6)+, AØ 
CLR.L CAB) 
RTS 

END-CODE MACH 


CODE unpack 
MOVE.L CA6), DØ 
CLR.L DI 
MOVE.W 00,01 
CLR.W DØ 
SWAP.W DØ 
MOVE.L 00, CA6) 
MOVE.L D1,-CA6) 
RTS 

END-CODE MACH 


Listing 2: The desk accessory 
C A multi-window, multi-menu, permanent desk accessory ) 
C J. Lengowski March 87 ) 


only forth also essembler also mac 
INCLUDE” general defs" 


BINARY 
000011011110 1010 CONSTANT DAEmask 


HEX 

А20 CONSTANT MBarEnable 
A88 CONSTANT CloseOrnHook 
1B4 CONSTANT SystemTask 


С *** close intercept routine *** ) 


HEADER inter.start 
HEADER DAName 
DC.B 10,0, 'Mach 2 DA’ 
HEADER trapaddr 
DCL Ø 
header inter.stəck 40 allot 
CODE setup. inter stack 
LEA -8CPC2,A6 С local stack grows downward from here ) 
RTS 
END-CODE 


: inter 
call frontwindow windowkind + @ 
2 © IF 
(71 trapaddr @ SystemTask call SetTrapAddress 
[^] DAName call OpenDeskAcc drop 
THEN 


CODE intercept 
MOVEM.L АЙ-А4/А6/00-07,-САТ) 


JSR setup. inter .stack 
JSR inter 
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MOVEM.L (АТ2%,А0-А4/А6/00-07 

MOVE.L trapaddr, -CA7) 

RTS 
END-CODE 
HEADER inter .end 
С for exportation 2 
“ trapaddr ” inter.start - CONSTANT *trapaddr 
‘ intercept ‘ inter.stert - CONSTANT *inter 
DECIMAL 


( *** start of desk accessory main code *** ) 


header testDA C marker for writing to DRVR resource ) 

header drvrFlags 2 allot 
header drvrdelay 2 allot 
header drvrEMask 2 allot 
header drvrMenu 2 allot 
header drvrOpen 2 allot 
header drvrPrime 2 allot 
header drvrCt! 2 allot 

header drvrStatus 2 allot 
header drvrClose 2 allot 
header drvrname 32 allot 


( *** main desk accessory routines *** ) 

( globals ) 

header temprect 8 allot 

header SizeRect 8 allot С grow size limits ) 
header NewSize 4 allot С for SizeWindow ) 
header penLoc 4 ellot( pen location ) 


header tempString 256 allot С for numeric conversion etc. ) 
header ButtonHdl 4 allot С for storage of control handle ) 
header closeflag 4 allot С for storage of close status ) 
header CurMenuList 4 allot € menu list temporary storage ) 
header CloseOrn 4 allot € CloseOrnHook temporary storage ) 


header window2 4 allot С second DA window ) 


header showflag 4 allot С state of 2nd window, 1: visible, 0: 


not) 
header myRes? 4 allot( local res 10=0 offset ) 
header temp 4 allot ( general purpose ) 


: @mouse ( | mousept - point ) 
^ mousept call getMouse mousept ; 


: cl C WPtr - ) portrect + call eraserect ; 
: {р cell drewstring ; 


: сга [*] penLoc call getpen 
10 € horizontal boundary ) 
[^] penLoc we 12 + 
call moveto 


: realclose ( | dCtlEntry ) 
MOVE.L A1,-CA6) 
-) dCtlEntry 
MOVE.L A4,-CA6) 
CASE 
aCtlEntry dCtlWindow + ё OF 
(71 closeflag off 


dCtlEntry dCtlRefNum + wê call CloseDeskAcc 


ENDOF 


[^] window2 ё OF 5 call sysbeep ENDOF 
ENDCASE 


; 
( *** event-handling routines *** ) 
: »oldMBar 
[^] CurMenuList @ call SetMenuBar 


call DrawMenuBar 
0 MBarEnable w! 
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д 


: ectivete-handler ( DAWind event-rec | menuID - ) 
(71 myRes@ ё -> menuID 
CloseOrnHook 6 [°] CloseOrn ! 
(^] realclose CloseOrnHook ! 
event-rec modifiers + #@ 1 and 
IF € window activated ) 
call frontwindow CASE DAWind OF 
menuID MBarEnable w! 
call GetMenuBar [^] CurMenuList ! 
call ClearMenuBar 
menuID call getRMenu 0 call InsertMenu 
menuID 1+ call getRMenu 0 call InsertMenu 
call drawMenuBar 
ENDOF 
ENDCASE 
ELSE >oldMBar С window deactivated ) 
[*] CloseOrn 6 CloseOrnHook ! 
THEN 


: update-handler ( DAWind event-rec | - } 
[^] penLoc call GetPen 
DAWind CALL BeginUpdate 
DAWind cl 
DAWind CALL DrawGrowIcon 
DAWind CALL DrawControls 
DAWind CALL EndUpdate 
(71 penLoc 2% wê (71 penLoc we 
call moveto С restore pen position ) 


: invalSize ( gort | br - ) 
gPort 4 + иё -> b 
gort 6 + иё -› г 
(41 temprect r 16 - Ø r b call setrect 
(^] temprect call invalrect 
(41 temprect Ø b 16 - r b call setrect 
(71 temprect call invalrect 


: mousedn-handler 
( DCtlEntry DAWind event-rec | 
whereM DAPort whichCt] whichWind 
mouseloc menuID menuRes wKind - ) 
(41 myRes® @ -> menuID 
DAWind portrect + -» DAPort 
event-rec where + 6 dup -> whereM -> mouseloc 
* mouseloc call GlobalToLocal 
whereM ^ whichWind call FindWindow drop С result code ) 


whichWind CASE 

DAWind OF 

DAWind windowkind + dup иё -> wKind 

8 swap w! (С set to application-created window ) 

whereM ^ whichWind call FindWindow 

CASE 
inGrow OF 
DAPort invalSize 
DAWind whereM ['] SizeRect call GrowWindow 
DAWind swap unpack swap -1 call sizewindow 
DAPort invalSize 
ENDOF 


inZoomIn OF 
DAWind whereM 7 call TrackBox 
IF DAPort invalSize 
DAWind 7 0 call ZoomWindow THEN 
ENDOF 


inZoomOut OF 
DAWind whereM 8 call TrackBox 
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IF DAPort invalSize 
DAWind 8 0 call ZoomWindow THEN 
ENDOF 


mouseloc DAWind ^ whichCt! call FindControl 
IF 
whichCt] mouseLoc Ø call TrackControl 
IF [°] window2 ё 
1 (71 showflag 6 - [^] showflag ! 
(71 showf lag ё 
IF call showwindow ELSE call hidewindow THEN 
THEN 
ELSE 
* Mouse down^ tp crd 
THEN 


ENDCASE 

wKind DAWind windowkind + w! С reset to DA window ) 
ENDOF 

(71 window2 6 OF 5 call sysbeep ENDOF 


ENDCASE 


7 


: update-cursor 


( DAWind | ~ ) 
@mouse DAWind portrect + call PtInRect 
IF call InitCursor THEN 


: getDrvrID ( dCtlEntry | - num ) 


dCtlEntry dCtiRefNum + wê 1. ext 
1+ negate 


: ownResID С resID drvrID ) 


5 shl + -16384 + 


: install.intercept ( dCtlEntry | procHdl ~ ) 


д 


“proc [^] myRes® @ call GetResource -> procHd] 
SystemTask call GetTrapAddr 

procHd! 6 *trapaddr + ! 

procHd] 6 *inter + SystemTask call SetTrapAddr 


: Open ( DCtlEntry ParamBlockRec | 


DAWind DAWind2 Res@ oldPort - ) 
^ oldPort call GetPort 
dCtlEntry dCtlWindow + e 
9- IF € not open already ) 
[^] closeflag on 
(71 showf lag off 
0 dCtlEntry getDrvrID ownResID -> Res 
Resø (71 myResO ! 
“proc Res@ call GetResource 
call ReleaseResource С remove from sysheap ) 
Res® dCtlEntry DCtlMenu + w! 
( menu ref has to be updated ) 
Веѕ0 0 Ø call getNewWindow -> DAWind 
DAWind dCtlEntry dCtlWindow + ! 
С store window pointer ) 
DAWind dCtlEntry dCtlRefNum + we 
swap windowKind * w! 
Res@ 1% Ø Ø call getNewWindow -> DAWind2 
DAWind2 (71 window2 ! 
DAWind2 dCtlEntry dCtlRefNum + we 
swep windowKind * w! 
DAWind call setport 
(“1 sizerect 50 50 500 320 call setrect 
1040 call moveto 
Res® DAWind call GetNewContro?l 171 ButtonHd] ! 
oldPort call setPort 
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ТНЕМ 


: Close ( DCtlEntry ParenBlockRec | - } 


д 


: Ctl 


dCtlEntry dCtlWindow + 
dup 6 call DisposWindow 0 swap ! 
С so that Open will work again 2 
(71 window2 6 call disposWindow 
[*] closeflag 6 IF DCtlEntry install.intercept THEN 
^oldMBer 


( DCtlEntry ParamBlockRec | 
DAWind oldPort event-rec menuID menuRes - ) 


* oldPort call GetPort 
dCtlEntry dCtlWindow + 6 dup -> DAWind call setport 
4 call textfont 9 call textsize 
DCtiEntry DCtlMenu + мё 1.ехі -> menuID 
PeremBlockRec csCode + wê 1l ext 
CASE 
goodBye OF 10 call sysbeep 
dCtlEntry ParamBlockRec Close 
(71 closeflag off ENDOF 
accEvent OF 
PeremBlockRec csParam + @ -> event-rec 
event-rec what + wê 
CASE 
mousedn-evt ОҒ 
DCtlEntry DAWind event-rec 
mousedn-handler  ENDOF 


keydn-evt OF DAWind cl 
DAWind call DrawGrowIcon 
DAWind call DrawControls 
10 40 call moveto 
* Key down.^ tp crd 
ENDOF 


eutokey-evtOF ENDOF 


update-evt OF 
DAWind event-rec update-handler ЕМООҒ 


disk-evt OF ENDOF 
ectivate-evt OF 
DAWind event-rec activate-handler  ENDOF 


network-evtOF  ENDOF 
driver-evt OF ENDOF 
ENDCASE 
ENDOF 
accRun ОҒ [“] window2 ё dup call setport cl 
4 call textfont 9 call textsize 
20 10 call moveto 
(71 temp call readdatetime drop 
(“1 temp ё -1 [°] tempstring 
call IUTimeString 
[°] tempstring tp 
ENDOF 
accCursor OF DAWind update-cursor ENDOF 
accMenu OF 
PeremBlockRec csParam + e 
unpack -> menuRes 
l.ext 
CASE menuID OF 
nenuRes 
CASE — 10F ^" Item1-1!^ tp crd ENDOF 
2 OF * Item1-2!^ tp crd ENDOF 
З OF * Itemi-3!^ tp сга ENDOF 
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4 OF “ Iten1-4!^ tp сга ENDOF 
6 OF * Item1-6!^ tp crd ENDOF 
ENDCASE ENDOF 
menuID 1* OF 
menuRes 
CASE 1 OF * Item2-1!^ tp crd ENDOF 
2 OF ~ Item2-2!^ tp сга ENDOF 
3 OF “ Item2-3!^ tp crd ENDOF 
4 OF * Item2-4!^ tp crd ENDOF 
6 OF ^ Item2-6!^ tp сга ENDOF 
ENDCASE 
ENDOF 
ENDCASE 
9 call HiLiteMenu 
ENDOF 
accUndo OF ENDOF 
accCut OF ENDOF 
accCopy OF ENDOF 
accPaste ОР ENDOF 
accClear ОҒ ENDOF 
ENDCASE 
oldport call setPort 


: OrStatus ( DCtlEntry ParamBlockRec | - ) 


д 


: Prime ( DCtlEntry ParamBlockRec | - ) 


4 


( *** glue routines *** ) 
header local.stack 1000 allot 


CODE setup.local.stack 
LEA -8CPC2,A46 С local stack grows downward from here ) 
RTS 


END-CODE 


CODE DAOpen 
MOVEM.L Аб-А 1,-САТ) 
setup. local .stack 
MOVE.L A1,-CA6) 
MOVE.L A®,-CA6) 
Open 
CLR.L 00 
MOVEM.L CA72*,A0-A1 
RTS END-CODE 


CODE DAClose 
MOVEM.L А0-А1,-(АТ) 
setup. local.stack 
MOVE.L Ai,-CA6) 
MOVE.L A®,-CA6) 
Close 
CLR.L 00 
MOVEM.L CA7)+,AQ-A1 
RTS END-CODE 


CODE DACtI 
MOVEM.L А0-А1,-(АТ) 
setup. local.stack 
MOVE.L A1,-CA6) 
MOVE.L А0,-САб) 
Ctl 
CLR.L 00 
MOVEM.L (А72%,А0-А1 
MOVE.L vJioDone,-CA7) 
RTS END-CODE 


CODE DAStatus 
MOVEM.L А0-А1,-САТ) 
setup. local.stack 
MOVE.L A1,-CA6) 
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MOVE.L A®,-CA6) 

DrStatus 

CLR.L DØ 

MOVEM.L (A72*,A0-A1 
RTS END-CODE 


CODE DAPr ime 
MOVEM.L А0-А1,-(А7) 
setup. local .stack 
MOVE.L А1,-САб) 
MOVE.L А0,-САб) 
Prime 
CLR.L DØ 
MOVEM.L (А72%,А0-А1 
RTS END-CODE 


header endDA 
( *** code written to DRVR resource ends here *** ) 


( *** initialization routines *** ) 


: setFlegs (*'] drvrFlagsw! ; 
: setDelay['] drvrDelay w! ; 
: setEMesk[^) drvrEMask w! ; 
: SetMenuID Г] drvrMenu w! ; 


: setOpen ['] drvrüpen w! ; 
: setPrime['] drvrPrime w! ; 
: setCtl [*] drvrCtl мі; 
: setStatus (*] drvrStatus w! ; 
: setClose[') drvrClose w! ; 


: setName ( addr len | target - ) 
(71 drvrName -> target 
len target c! 
addr target 1% 
len 31» if 31 else len then 
cmove 


o 


write resource to file ) 

: $create-res ( str-addr - errcode ) 
call CreateResF ile 

call ResError L. ext 


: $open-res ( addr | refNum - refNum or errcode ) 
addr call OpenResFile -? refNum 
call ResError L.ext 
?dup IF ELSE refNum THEN 


: close-res ( refNum - errcode ) 
call CloseResF ile 
call ResError L.ext 


: make-res ( addr len rtype ID name | - ) 
eddr len call PtrToHand 
abort” Could not create resource handle” 
rtype ID name call AddResource 


: write-out ( filename | refnum - ) 
filename $create-res 


abort” That resource file already exists” 


filename $open-res 
dup 0< abort” Open resource file failed” 
-) refnum 
refnum call UseResFile 
(71 testDA ГС“) endDA over - 
“drvr 12 “ Mach 2 DA" make-res 
[^] inter.start ['] inter.end over - 
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“proc -16000 " Mach 2 DA” make-res ," 16000 


“proc -16000 call GetResource First 
dup 80 call SetResAttrs С 64: sysheap + 16: locked ) Item 1-1 
call ChangedResource Item 1-2 
refnum close-res abort” Could not close resource file” Item 1-3 
» Item 1-4 
(- 
: init-DA Iten 1-6 
( initialize offsets ) 
(71 DAOpen [^] testDA - setOpen Type MENU 
(71 DAPrime [^] testDA - setPrime ,7 15999 
(71 DACtI [°] testDA - setCtl Second 
(^) DAStatus Ї['/] testDA - setStatus Iten 2-1 
[^] DAClose[*] testDA - setClose Item 2-2 
( initialize driver name ) Item 2-3 
* Mach 2 DA” count setname Item 2-4 
( initialize driver flags, (s 
NeedLock, NeedTime, NeedGoodBye, CtlEnable ) Item 2-6 


[ hex 1 7400 setFlags [ decimal ] 
С initialize delay time ) 


69 setDelay Type WIND 
С initialize event mask, events recommended in IM ) ,7 16000 
DAEMask setEMask Mach2 Desk Accessory 
С initialize menu ID, local 10=0 for DRVR 10=12 ) 240 10 320 250 
- 16000 setMenuID C careful! this field will NOT be changed Visible GoAway 
by the DA Mover when ID is changed ) 8 
0 
д 
: make-DA Type WIND 
init-DA ,7 15999 
“ Mach2 DA.rsrc^ $delete drop Time 
* Mach2 DA.rsrc^ write-out 140 400 165 500 
} Invisible GoAway 
Listing 3: RMaker input file 0 
* Resources for MACH 2 desk accessory Tgpe CNTL 
, 16000 
Mach2 DA Time 
DF ILDMOV 10 10 27 50 
Visible 
INCLUDE Mach2 DA.rsrc 0 
0 
Type MENU 000 
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Forth Forum 


Custom Menu Definition 


"Pascal calling and menu definition routines" 


Once again, this month's excursion will take us into a field that 
is unusual for threaded code languages on the Macintosh: we will 
define acustom menu routine entirely in Mach 2 Forth and create 
the necessary glue code that is needed to call this routine as a 
Pascal procedure, the way the Toolbox expects it. 

The subject as such had already been addressed by Darryl 
Lovato (У2#8), where he redefined the standard menu definition 
procedure in TML Pascal. Besides giving you one more example 
of 'kernel-independent' Forth code, I chose this topic to illustrate 
the concept of Pascal parameter passing in Forth (discovering on 
the way one potentially awful bug in the desk accessory glue code 
that I wrote recently. Read on.). 

We'll also have some Forth bits recently sent to me by Juri 
Munkki (the creator of the TED editor task), and some news on 
further Mach2 developments. But first, to our main theme. 


Menu Defintion Routines 


The format of a menu is record is given below. 
resource menu record 


menu height 


handle to 
definition procedure 


enable flags (see Inside Mac 1-345) 


menu title (counted string of length n) 


menu data 

contains item names, icons, key eqivalents, 
check marks, text styles 

for details see listing 1 


Fig. 1: Format of a MENU resource 


As you might know, the routine that is used by the Menu 
Manager to draw a menu is keptin a MDEF resource. Since each 
menu contains information on the ID of its corresponding MDEF 
resource, the menu definition routine may be changed easily by 
changing the routine ID in the MENU resource. (Fig. 1). The 
standard Macintosh MDEF (contained in the Мас+ ROMS) has 
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an ID of O. If the menu resource contains a different ID, that 
MDEF will be loaded and a handle to it put into the menuProc 
field of the menu record. Alternatively, one may install the menu 
with its old ID, and substitute the handle afterwards. 

In order to write our custom menu definition routine in Forth, 
we need to know some details about the parameters that are 
passed to it and how they are located on the stack. The menu 
definition routine is a Pascal procedure defined in the following 


way (IM): 


procedure MyMenu (message: INTEGER; theMenu: MenuHandle; 
VAR menuRect: Rect; hitPt: Point; VAR whichltem: INTEGER); 


with the parameters 


message: 0, 1, or 2. 0 is mDrawM sg, telling the menu routine 
to draw the menu within the bounds given by menuRect. 1 is 
mChooseMsg, which tells the routine that the menu item corre- 
sponding to the mouse location in hitPt should be highlighted and 
its number returned in whichltem. 2, mSizeMsg, indicates that the 
menu's dimensions should be calculated and stored in the 
menuWidth and menuHeight fields of the menu record. 


theMenu a handle to the menu record from which the routine 
was initiated. 


menuRect: the rectangle, in global coordinates, in which the 
menu is located. 


hitPt the mouse location, in global coordinates, when the 
routine was called. 


whichltem on entry contains the item number of the last item 
selected and on exit the number of the new item selected. 


The menu manager expects the entry point to the routine to be 
at the beginning of the MDEF resource. Since the entry point to 
the highest-level Forth word is usually somewhere near the end 
of the code, this will require some hacking with vectors. 

Fig. 2 shows how the stack looks like on entry to the routine. 
As usual, the top of stack (lowest in memory) contains the retum 
address, followed by the parameters. What our glue code has to 
do is to save the return address somewhere, move all parameters 
from the A7 to the Forth stack (A6), save the contents of all 
registers, and call the Forth routine. On exit, the registers should 
be restored, before returning through an RTS. Fig. 3 shows a 
possible stack arrangement just before entering (or after exiting) 
the Forth routine. 
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Fig.2: Parameter setup for MDEF routine 


Fig3: Simple method of calling Forth 
routine 


This simple method, however, has some drawbacks. In order 
to put the parameters on the Forth stack, we have to define an A6 
stack space first (thereby changing A6), so the registers will have 
to be saved before the parameters are transferred. That by itself 
is not a big problem, in fact it is the standard method for Pascal 
procedure calling. The other problem is with setting up the A6 
stack. In earlier columns I included routines for stack setup in the 
glue code, defining stack space within the code space. Although 
this will do the job, it completely precludes re-entrancy and can 
be space-consuming if different routines cannot share the same 
stack space. Therefore, this time I'll describe an improvement 
that is also much closer to the Pascal calling conventions. 


In Pascal routines, the first instruction usually is a 
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LINK Аб, -ппп 


where nnn is the number of bytes to reserve ол the stack for 
local variables. The LINK instruction will push the current 
value of A6 on the stack, copy A7 to A6 (thereby making A6 
point to the top of stack), and reserve nnn bytes on the stack, 
changing A7 accordingly. Before we exit the routine, we'll 
have an 


UNLK A6 


which reverses the action of LINK: it replaces A7 with the 
current value of A6 and pops the top of stack into A6, thereby 
restoring Аб and A7 to the values they had on routine entry. 


To get rid of the parameters on the stack, we then put the return 
address into AO 


MOVE.L (AT), A0 


pop the parameters (m bytes) off the stack 


ADD.L #m,A7 


and leave the routine through the return address 


JMP (A0). 

The glue code at the end of listing 1 implements this calling 
procedure. Its advantage is that after the LINK instruction we 
may peacefully save the registers on the stack, preserving A6 as 
a pointer to our parameters (they start at 8(A6)). Also, we have 
automatically created a local variable space (512 bytes in our 
example) which serves as a Forth stack with A6 already aligned 
in the proper way. Since the Forth stack is located within a stack 
frame in the A7 stack, re-entry is no problem (remember, though, 
that some applications don't provide too much A7 stack space, so 
be careful). 

Half the local stack space is devoted to the A3 stack, which is 
the loopreturn stack in Mach2. A3, too, is set up by the glue code. 
And here comes the potential bug in my DA routines that I had 
already mentioned: those glue routines do not contain support 

for an A3 stack. Since I did not use DO...LOOPs in the examples, 

there were no problems, but should you use that code to develop 
other desk accessories that use loops, be careful to add the extra 
A3 setup. 


Messages to the MDEF routine 


Now that we have passed all the parameters to the menu 
definition routine in the right way, what are we going to do with 
them? We have to write a routine that handles the three possible 
message, mDrawMsg, mChooseMsg and mSizeMsg. 

Our custom menu will look like the one in Fig. 4. 
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1:29:05 ` 


Nae tal 

eH ta ye tt Pa NI A tate atte 

Donors neat на — ИТ... ТАР ЕХ ХХР oe he he Re cree а АР ge aa 
eee eee АЧА ШШ ee ay dw кабат aa a 


Fig. 4: Output from the custom MDEF routine 


A simple four-by-four palette arrangement of fixed size (100 
by 100 pixels in the example). The item number returned will be 
from 1 to 16, and we do not take into account whether a menu item 
is disabled or not. 

The three possible messages are handled in a CASE statement 
which forms the main body of the MDEF routine. Refer toListing 
1 to see how they work. First, the menu width and height are 
recalled from the menu record, and the sizes of the palette 
rectangles calculated (wd and ht). The top and left coordinates of 
the menu rectangle are obtained from menuRect. The CASE 
statement follows, where the Draw message simply draws six- 
teen little boxes into the menu rectangle, filling them with some 
patterns. These patterns are part of the Quickdraw global vari- 
ables, to which the words white, etc. provide access. 


The Size message stores the menu's dimensions in the menu 
record. 


The Choose message is the most complicated one: whichItem 
on entry contains the number of the item selected last (zero if 
none). The item rectangles are scanned, one after the other, to see 
whether ЛИР! is in one of them. If so, the new item number is 
calculated and compared to the old one. If they are the same, 
nothing is done; if they are not, both the new and the old item 
rectangles are inverted and the new item number returned in 
whichltem. If the new mouse location does not correspond to any 
item, we just invert the old item and return zero in whichltem. 

At the end of the listing, code is provided to install the new 
MDEF routine in the header of an existing menu for testing (and 
to remove it, of course). To get the IDs of the menus installed in 
the Mach2 system (or any other Forth you might transport this 
code to), the word list.menus is defined near the beginning of the 
listing. Finally, at the very end I added some code to write a 
MDEF 1 resource to a new resource file so that you may install 
this custom menu with ResEdit. 


Feedback dept. 
I recently received some more mail from Juri Munkki, who 


already had an article in this magazine. It deals with implement- 
ing animation under Mach2 and you'll read about it very soon; for 
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now just a clever trick that I found in the code. ANEW «word», 
used at the beginning of a file to forget the previous definition, is 
very useful and does not exist in Mach2. A redefinition using 
FORGET was possible in Mach2.0, but no more in 2.1, since 
FORGET is not a global definition anymore. Listing 2 shows 
Juri's hack to circumvent that problem: he takes the definition of 
DUMP, which is defined (global) just before FORGET in the 
dictionary, and uses it as a pointer to access the FORGET code. 
Try out for yourself. There is also a word that will return heap 
space for a variable that contains a handle. 

The new Mach2 update, containing the editor, is on its way (as 
of beginning of May). In addition to the editor (still only single- 


window, sorry to say), the debugger has the bus, address, etc. 
error handlers fixed: they return back directly into the Forth 
system. Also, a switch is included by which you can select to 
enter TMON (or any other debugger) or the Forth debugger upon 
pressing the interrupt switch. For customizing, the source code of 
the I/O task is included, and the SANE handling has improved 
(like error traps etc.). I might tell you more about it next time 
when I've received my copy. 
For this time, happy threading. 


Listing 1: Menu definition routine 

€ € J. Lengowski/MacTutor ) 

( *** menu definition procedures. J.L. April 1987 *** ) 
ONLY FORTH ALSO ASSEMBLER ALSO MAC 


HEX 

40444546 CONSTANT "mdef 
0 CONSTANT mDrawMsg 

1 CONSTANT mChooseMsg 
2 CONSTANT mSizeMsg 
DECIMAL 


CODE white 
MOVE.L (A5),-(A6) 
SUBQ.L #8, (Аб) 
RTS 

END-CODE MACH 


CODE black 
MOVE.L (A5),-(A6) 
SUBI.L #16, (A6) 
RTS 

END-CODE MACH 


CODE gray 
MOVE.L (À52,-CA6) 
SUBI.L #24, (Аб) 


RTS 
END-CODE MACH 


CODE 1tgray 
MOVE.L (A52,-CA6) 
SUBI.L #32, (Аб) 
RTS 

END-CODE MACH 


CODE dkgray 
MOVE.L CA5),-CA6) 
SUBI.L #49, (Аб) 
RTS 

END-CODE MACH 


© The Essential MacTutor, Vol. 3 


CODE w* 
MOVE.L (A62*,D1 
MOVE.L (A62*,D0 
MULS.W 01,00 
MOVE.L 00,-САб) 


RTS 
END-CODE MACH 


CODE w/ 
MOVE.L (A6)*,D1 
MOVE.L (A6)*,D0 
DIVS.W 01,00 
EXT.L DØ 
MOVE.L DØ,-CA6) 
TS 


R 
END-CODE MACH 


CODE w/mod 
MOVE.L (A62*,01 
MOVE.L (A62*,D0 
DIVS.W D1,DØ 
MOVE.L 00,01 
SWAP.W D1 
EXT.L 01 
EXT.L DØ 
MOVE.L 01,-(Аб) 
MOVE.L DØ, -CA6) 
RTS 

END-CODE MACH 


( *** menu record data structure *** ) 


0 CONSTANT menuID ( integer ) 
2 CONSTANT menuWidth ( integer ) 
4 CONSTANT menuHeight С integer ) 
6 CONSTANT menuProc ( handle ) 


10 CONSTANT enableFlags € longint ) 

14 CONSTANT menuData С Str255 and other data ) 
*** menu Data format *** ) 

counted string: menu title ) 

followed by 1 to 31 times: ) 

counted string: menu item ) 

byte: item icon # ) 

byte: equivalent character ) 

byte: check mark character ) 

е attributes ) 


“м 78 "м ж» у^“ ж» 978 жа Қа» 0 


end: zero byte. ) 


: list.menus 
32767 Ø do 
i call getMhandle 
?dup ТК." Menu 8 " i . ." , handle " dup . cr 

." MenuData:" cr 

6 menuData * dup count type cr 

( type menu title ) 
dup cê + 1+ C start of first item string 


BEGIN 
dup count dup 
WHILE type cr 
dup c@ + 5 + 
REPEAT drop 
THEN 
PAUSE loop 


; 
( *** code moved to custom menu routine space starts here *** ) 
header start 

JMP start С to be filled later ) 


header temprect 8 allot 
header itemrect 8 allot 
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( redefine multiplication and division words ) 

( so they remain local to our code, not relative ) 
С to application globals ) 

0x WX c 


! / w/ 
: /mod w/mod ; 


: mdef ( message theMenu menuRect hitPt whichItem | 
width height wd ht top left item? wit -- } 
theMenu 6 dup menuwidth + wê -> width 
width 4 / — wd 
menuheight + мё -» height 
height 4 / — ht 
menuRect wê -> top 
menuRect 2+ мё -> left 


message CASE 
mDrawMsg OF С draw menu ) 
height 0 DO 
4 0 DO 
(“1 temprect 
left i wd * * top j * over wd * over ht 


call setrect 
['] tempRect 4 4 
i CASE 0 OF white ENDOF 
1 ОҒ 1tgrey ENDOF 
2 OF gray ENDOF 
З OF dkgrey ENDOF 
black С shouldn't occur ) 
ENDCASE CALL FillRoundRect 
("1 tempRect 4 4 CALL FrameRoundRect 
LOOP 
ht *LOOP 
ENDOF 


mChooseMsg OF С choose item ) 
whichItem wê -> мій 
['j) ItemRect 
wit 1- 4 /mod ht * top + swap wd * left + swap 
over wd * over ht * call setrect 
hitPt menuRect call PtInrect 


1j4** 1+ -> item# 
['] temprect 
left i wd * + top j ht * + 
over wd * over ht * call setrect 
hitPt ['] tempRect call PtInRect 
IF item? wit О 
IF [') ItemRect 4 4 call InvertRoun- 
dRect 
['] tempRect 4 4 call InvertRoun- 
dRect 
item® whichItem w! 
THEN 
THEN 
LOOP 
LOOP 
ELSE 
wit IF ['] ItemRect 4 4 call InvertRoundRect THEN 
0 whichItem w! 


mSizeMsg OF ( our sizes are constant ) 
100 theMenu @ menuWidth + w! 
100 theMenu 6 menuHeight + w! 
ENDOF 
ЕМОСАЅЕ 


) 


( *** glue routine *** ) 
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CODE custom.menu 
LINK A6,#-512 С 512 bytes of local Forth stack ) 
MOVEM.L A@-A5/D@-D7,-CA7) С save registers ) 
MOVE.L A6,A3 ( setup local loop return stack ) 
SUBA.L #256, АЗ С in the low 256 local stack bytes 


) 
MOVE.L 8(A62,D0 C VAR whichItem: INTEGER ) 
MOVE.L 12(А6),01 C hitPt: Point 2D 
MOVE.L 16CA6),AØ С VAR menuRect: Rect ) 
MOVE.L 20€A6),A1 С theMenu: MenuHandle ) 
MOVEQ.L 80/02 
MOVE.W 24(А62,02 С message: INTEGER ) 
MOVE.L D2,-CA6) 
MOVE.L A1,-CA6) 
MOVE.L Аб, -САб) 
MOVE.L D1,-CA6) 
MOVE.L 00, -САб) 
JSR mdef С call Forth routine ) 
MOVEM.L (A72*,A0-A5/D0-D7 ( restore registers ) 
UNLK A6 
MOVE.L САТ)+, Ад ( return address ) 
ADD.W %18,A7 С pop off 18 bytes of parameters ) 
JMP (AQ) 
END-CODE 
header end 
' custom.menu ' start 2+ - ' start 2+ w! 


( *** installation *** ) 
veriable Hregular 


: install.custom ( menu® | mh procH -- ) 

menu call getMHandle -> mh 

mh Ø= abort" Non-existing menu ID given." 

("1 start (') end over - call PtrToHand 
ebort" Can't get enough memory to install." 
-) procH 

mh call HLock 

mh 6 menuProc + 6 Hregular ! 

procH mh 6 menuProc * ! 

mh call HUnLock 

cr 


: remove.custom ( menut! | mh procH -- ) 
menu® call getMHandle -> mh 
mh = abort" Non-existing menu ID given." 
nh call HLock 
mh 6 menuProc + @ call DisposHandle 
Hregular @ mh 6 menuProc + ! 
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mh call HUnLock 
"OE cu 


2 


( *** making 8 resource *** ) 
: $create-res call CreateResFile call ResError L_ext ; 


: $open-res ( addr | refNum -- result ) 
addr call openresfile -> refNum 
call ResError L.ext 
dup not IF drop refNum THEN 


: $close-res call CloseResFile call ResError L.ext ; 


: meke-mdef ( | refNum -- ) 
" mdef .res" dup $create-res 
abort” You have to delete the old 'mdef .res' file first." 
$open-res dup -> refNum call UseResFile 
['] start ['] end over - call PtrToHand drop С result code 


"mdef 1 " Mach2 MDEF" call AddResource 
refNum $close-res drop ( result code ) 


Listing 2: some Mach2 tricks from Finland 
€ Juri Munkki, April 1987 ) 


: ANEW ( | LEN ) 
32 WORD DUP C@ 1+ NEGATE -› LEN 
FIND SWAP DROP 
IF .s LEN >IN +! | 
(“1 DUMP € dump is defined just before FORGET 2 
2* 6 6 * EXECUTE CALL DRAWMENUBAR THEN 
LEN >IN +! 
CREATE DOES» DROP 


4 


( Неаруаг: 
Used in the form: HEAPVAR VARIABLE. NAME. 
If VARIABLE_NAME exists, it returns the handle 
from VARIABLE.NAME to the heap. It should be used 
before ANEW to free space from the heep. ) 
: HEAPVAR 
32 WORD 
FIND IF LINK»BODY EXECUTE 
@ DUP 
IF DUP CALL HUNLOCK DROP 
CALL DISPOSHANDLE DROP ELSE DROP THEN 
ELSE DROP pem 


| THEN Sel 


cats, 
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Forth Forum 
Starflight in the Forth Dimension 


Starflight Demo in Forth 


We'll have another contribution from our active reader in 
Finland this month. Juri Munkki has worked out some graphics 
animation routines in Mach 2 which will work with either the 
alternate screen buffer (fast, but not supported on the Mac II) or 
with a separately defined off-screen buffer (slower, but Mac II - 
compatible). The program example is Mike Morton’s Starflight 
demo, rewritten in Forth. In the course of this article, we will not 
only learn something about animation in Forth, but also of things 
to consider in a turnkey application when the alternate screen 
buffer is used. 

Finally, I'll briefly inform you about the latest release of 
Mach2 (v2.11). But let's first look at the graphics animation 
demo and the comment that I received from Juri with it. 


The Many Faces of the 
Alternate Screen 


Animation is the basis of all arcade games. А microcomputer 
fast enough to satisfy the needs of every games programmer has 
yet to be designed. An alternate graphics buffer is very useful in 
eliminating flicker. The program can draw on a buffer while the 
user is watching the other buffer. When the frame is ready, it is 
displayed and the previously visible buffer is hidden. 

Double buffering is available on the Mac 128K, 512K and 
Plus, but it is not available on the Mac II and probably will be 
missing or different in future Macintosh models. Because of this, 
the programmer must choose between fast animation and future 
compatibility. This choice has usually been made at the time the 
program is written, but doesn't have to be that way. 

In this article I will present a basis of a double-buffering 
animation system. I have written two interchangeable programs 
that eliminate flicker from animation. The first program can not 
be used on machines that don't have the alternate screen, but it is 
much faster than the other one. The second program should work 
on all computers. 

The second program allocates 22K of RAM and draws only 
to this place. It then copies the result to the screen with CopyBits. 
It takes more time because we have to make the copy instead of 
flipping one bit in the VIA. 

There are three main routines: InitAnim, StartDraw and 
ShowB. In addition to these the program may access a handle to 
the drawing buffer. An animation program starts by calling 
InitAnim, which may relaunch if the alternate buffer is not 
available. StartDraw is called before drawing an animation 
frame. It clears the buffer to black and makes Grabu the “handle” 
to the buffer. You may draw directly in the buffer with his own 
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routines or you can use QuickDraw. When the frame is finished, 
acall to ShowB will either copy it onto the screen or it will switch 
display buffers. 


Freeing the Alternate Buffer 
for Animation 


Gaining access to the alternate buffer has never been easy. 
With the old ROMS the program had to launch itself to move the 
stack below the screen memory. New ROMs place the cache 
RAM on the alternate screen buffer. [Get the idea that Apple is 
discouraging our use of this feature? -Ed] 

Most animation programs don't work with the cache on 
because they write directly on the cache memory. The segment 
loader isn't smart enough to move or clear the cache when it is 
asked to launch a program with the alternate screen option set. 
(See fig. 1) | 

Fortunately it was very easy to guess where the cache settings 


БІСЛЕН  vasySuus — 
sofe | — Fw —— 
sefe | Pe —— 
зао а ^m 
reece |e БЕГІС БЕНЕН 
о | | —— 
see s | — voci —— 
sxe[2| mo — -— 
ЕСЛЕН | cares 
ов [7] caron 7 


Bit 5 ($20) of this location 
is 1 if the cache is on, 
otherwise it is O. 


Figure 1, Parameter RAM 
were located. Since they are saved even when the computer is 
turned off, they had to be in the parameter RAM. The parameter 
RAM is located in the clock chip and it can hold 20 bytes. I 
examined the parameter RAM with different cache settings and 
the results can be found in figure 1. Since the old ROMs used only 
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18 bytes, the cache settings are saved in the two remaining bytes. 
(Note that all of this discussion assumes a Mac Plus configura- 
tion. If the Mac SE and the Mac II are different, I have not fully 
covered or mentioned those differences) 

The cache is never changes while an application is running. 
The segment loader changes the size of the cache when a new 
application is launched. It looks at the RAM copy of the parame- 
ters to determine if the cache needs to be changed. We can keep 
the original cache settings in the clock chip while relaunching 
and restore the original settings by calling _Initutil. (See fig. 2) 

Of course, there is a catch. The new ROMs contain an 
interesting feature. (feature: a bug as described by the marketing 
department, ref: APPLE ][ reference manual) If the segment 
loader has to remove the cache, it forgets to allocate the alternate 
buffer. If the program now looks at CurPageOption, it will see the 
value it gave when launching and happily overwrite its own 
stack. 

The program has to launch itself twice if the cache is on (Fig. 
2). The first time it turns the cache off and tries to launch with the 
alternate screen in case apple changes the ROMs again. The 
second time around it probably detects that the stack is in the 
wrong place and relaunches. This time the segment loader 
doesn’t have to change the cache, so it gives some thought to the 
alternate screen. The third time around, there should be no need 
to relaunch and the program continues. 


Jórg's Commentary 


As Juri’s examples contains a lot of new interesting defini- 
tions that can be useful in other contexts, I'll add some explana- 
tory remarks. First, you won’t be able to run the alternate screen 
buffer version of the demo if you have things installed in high 
memory that would be overwritten. TMON is an example of a 
resident program that won’t work with programs using the 
alternate screen, except if you install it in the system heap. 
Second, testing the first version from Mach2 (not having TURN- 
KEYed the program) will most probably throw you back into 
Mach2 again if a condition arises that causes the program to 
relaunch itself. Then you should reload the demo and start again. 
The second version with an off screen buffer defined independ- 
ently of the alternate screen will have none of these problems as 
long as enough buffer memory (22K here) is available. 

We have already seen (in the last column) the new version of 
ANEW that will work with Mach2.1 (and Mach2.11 as well). 
You find other words, like RECT etc., known from MacForth but 
absent in Mach2. 4ASCII is very useful to create 32-bit ASCII 
names - for resource names, etc. 

ZPSET (in the last part of the demo) is a routine that clears 
(i.e. sets to white) a point ina graphics buffer (which might be the 
screen itself) given its X- and Y- coordinates. It requires the 
previous definition of a handle GRABU to this graphics buffer. 
In the code for ZPSET, you should carefully look at the way the 
X-coordinate is converted to a row and bit address. The row 
column number is just X/8, and the remainder of X/8 is inverted 
to get the bit address within the row byte. This is because, 
counting X from left to right, a higher X actually corresponds to 
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Alternat« 
Launch Stage 


Stage one: 
The Finder launches our program. 
The cache is probably on and we 

have one screen buffer allocated. 


Stage two: 
The application has launched itself 
because CurPageOption was zero. 
The cache is now off, but we may 
still have only one buffer because of 
a bug in the segment loader. 

The program checks if the stack is 
located in the alternate buffer. 


Stage three: 
The program has launched it the 
second time because the stack was 
was located in the alternate screen 
buffer. 

This time the buffer is free and we 
can restore the original cache setting 
by loading it from the clock chip 
RAM with ап  InitUtil call. 


Figure 2, The Segment Loader Bug 


a lower bit within one byte. ZPSET furthermore assumes that 
each line is 512 points (64 bytes) long, which makes calculation 
of the offset from the Y-coordinate easy, simply shift by 6 bits. 
I+ and W/ come in handy to speed up integer arithmetic. 

The alternate screen version of the demo (code between the 
definitions DOUBLEBUFFERING and Updatescreen) is 
hardware-dependent only in the sense that it requires an alternate 
screen which can be switched on and off by setting a bit in the 
VIA, that this screen starts 32K below the normal screen and is 
512 by 342 pixels big. Absolute addresses are taken from the 
corresponding global memory locations, offset from A5 for the 
screen and in low memory for the VIA. 

The word OTHERPAGE will flip from one screen to the 
other, returning 0 or 1 depending which screen is used. This is 
done by directly addressing the VIA chip. GOFORTH is used to 
start the program; if the alternate screen memory is not available, 
it will relaunch until it is. 

The words contained in this part of the program are redefined 
in Listing 2 for working with Mac video setups that do not have 
the alternate screen. To use it, simply insert the code at the 
position indicated in the listing. Although this version is slower 
than the first one, it is the only one that would work on a Мас. 
I'm being cautious here, since I do not yet have a МасП to play 
around with, but Idon't see why it shouldn't work; except for the 
different screen dimensions, which are still assumed to be 512 by 
342. For the MacII, of larger screens, this would have to be 
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changed accordingly. 

Inthe second version, a separate graphics buffer is defined for 
drawing, which is dumped to the screen using CopyBits each time 
the screen is updated. If the screen dimensions are always 512 by 
342, you can use BlockMove instead of CopyBits, which is 
slightly faster. The ClearBuf routine still assumes the Mac512/ 
+/SE screen dimensions and would also have to be changed for 
other screen sizes. 

Juri also sent me a very interesting example of line drawing 
animation making use of the same concepts as outlined above. 
I'm not including that here because of space limitations; we 
might, however, see it in a later column. 


Latest Mach2 update - v2.11 


Mach2 finally has an editor. Single-window yet, and no 
command line capability, but works well. To keep two files open 
at the same time, you still have MockWrite. The new Mach2 
release has - of course - some bugs corrected, most important for 
me is that the debugger now works flawlessly, and integrates 
itself very nicely with other debugging environments such as 
TMON. There is a DEBG resource (one long word), which when 
zero, doesn't activate the debugger when Масһ2 is launched, 
when non-zero, activates it, but when it is 22, pressing the 
interrupt button will transfer you to TMON or whatever debug- 
ger you have installed instead of the Mach2 debugger. 

The assembler has been changed to include 68881 codes (no 
68020 code yet, this has to be simulated by DC.W XXXX 
instructions), and some bugs have been removed. 

The SANE interface has been extended and now includes all 
functions defined for the SANE packages. Integer arithmetic on 
the 68020 is speeded up by a package of 68020 definitions for the 
basic integer operations which may be substituted for the normal 
definitions. 

The source code for the I/O task (which is the equvalent of the 
main event loop in Mach2) is included in full, may be modified 
and the modified version integrated into the Mach2 application. 
This allows you to even further customize the behavior of 
standard Mach2 objects (windows, controls etc.); especially 
important if you want to have exact control over the points where 
task switching can occur. 

MPW may now be usedasa 'scripting' environment to create 
large Mach2 applications. Which means, of course, that one may 
maintain the code with Make and the likes. [Does this mean we'll 
soon have an MPW-compatible Mach2 and I can call my Forth 
words from Pascal or vice versa?? Shouldn’t be too difficult...) 

The update also included System 4.1 and Finder 5.5, which 
was good for me since they hadn't been officially available at that 
time for us Frenchies. 


Un petit mot pour les Francais 


As you may or may not have heard, MacTutor will be present 
at this year's AppleExpo in Paris at the beginning of October. 
Serge Rostan - from Infotique - is organizing a get-together of 
Macintosh developers and people from MacTutor on this occa- 
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sion. If you are thinking of going to the conference and joining 
that meeting, you should contact him (see Infotique's advertise- 
ment in this issue for a phone #). We are all looking forward to 
some exciting discussion! [Discussion, heck! Laura is looking 
forward to the romance of Paris. I wanted to bring our bicycles, 
but she objected! -Ed] 


Listing 1: Starflight demo, alternate screen version 
€ € Juri Munkki for MacTutor ) 


С Notice: this program was edited for publication which might 
have introduced minor errors. 
If you have the Ram cache set, the alternate screen version 
will ONLY work as а turnkey application. Clear the cache 
BEFORE starting Mach2 for testing this version from within 
Mach2. Also make sure you have not installed TMON or other 
nasty things in high memory. 
- JL- 

) 


ONLY FORTH DEFINITIONS 
ALSO MAC ALSO ASSEMBLER 
С Anew: Used in the form: ANEW PROGRAM_NAME . 
It tries to find the PROGRAM. NAME and forget it if it is 
found. 
It then creates PROGRAM МАМЕ and continues. It should be 
used in the beginning of the program. Old versions are then 
eutomatically forgotten, if they exist. ) 
: ANEW ( ) 
32 WORD DUP C8 1% NEGATE -> LEN 
FIND SWAP DROP 
IF .s LEN DIN +! 
[°] DUMP С dump is defined just before FORGET ) 
2+ @ 6 + EXECUTE CALL DRAWMENUBAR THEN 
LEN >IN +! 
CREATE DOES» DROP 


~ ~ 


Heapver : 
Used in the form: HEAPVAR VARIABLE. NAME. 
If VARIABLE_NAME exists, it returns the handle from 
VARIABLE-.NAME to the heap. It should be used 
before ANEW to free space from the heap. ) 
: HEAPVAR 
32 WORD 
FIND IF LINK»>BODY EXECUTE 
@ DUP 
IF DUP CALL HUNLOCK DROP 
CALL DISPOSHANDLE DROP ELSE DROP THEN 
ELSE DROP 
THEN 


9 


: ВЕСТ 

CREATE 

SWAP 2SWAP SWAP 
W, М, И, W, 


) 


GLOBAL 

CODE !RECT 
MOVE.L 
MOVE .W 
MOVE .W 
MOVE .W 
MOVE .W 
ADDA .L 
RTS 

END-CODE 


(A62*,A0 
14(A6), CAD )+ 
10(A6), CAB )+ 
6(A6), (А00% 
2(А6), (AD)+ 
! 16, A6 


GLOBAL 
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CODE OFF 


MOVEA.L — (Аб)+,А@ 
CLR.L — (A0) 
RTS 

END-CODE 

MACH 

GLOBAL 

CODE ON 
MOVEA.L  CA6)+ AØ 
MOVE.L 8-1, CAD) 
RTS 

END-CODE 

GLOBAL 

CODE SCALE 
MOVE.L (Аб),00 
BMI.S ei 
MOVE.L — (A62,D1 
ASL.L 00,01 
MOVE.L 01, (Аб) 
RTS 

@1 MOVE.L —(A62,D1 
NEG.L 00 
ASR.L 00,01 
MOVE.L 01, CA6) 
RTS 

END-CODE 

GLOBAL 


CODE @MOUSE 
SUBQ.L 54,А6б 
MOVE.L — A6,-CATD 
_GETMOUSE 
RTS 
END-CODE 


€ 4ASCII nnnn 
converts the 4 character string into its numeric value. It 
can only be used in the immediate mode. Examples below ) 
: 4ASCII 
0 
4 0 00 
8 SCALE 0 WORD 1+ Ce + 
LOOP 


д 


С *** The part that has to be exchanged with Listing 2 on 
machines without the alternate screen memory starts here *** ) 


ANEW DOUBLEBUFFERING 


С Low RAM location of system parameters ) 
504 CONSTANT SYSPARAM 


( Segment loader global containing last page request ) 
HEX 936 CONSTANT CURPAGEOPT ION 
910 CONSTANT CURAPNAME 
С VIA base address from apple's equate files ) 
104 CONSTANT VIA 
С offset to buffer А. The screen bit is there ) 
1Е00 CONSTANT VIABUFA 
( Bit 62$40 is the video bit ) 
40 CONSTANT VIOEO2 


EQU VIAq $0 104 


C offset to buffer B. The sound bit is there. 
We don’t use it yet... leter we might write 
а simple sound driver using this location  ) 
0 CONSTANT VIABUFB 
1 CONSTANT SOUNDBITS € Volume ) 
3 CONSTANT SOUNDPAGE С Bit 3=Sound page ) 
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EQU VIABUFBq $0000 
DECIMAL 


€ Pointer to upper left of screen ) 
VARIABLE SCREENMEM 

( Pointer to upper left of graphics buffer ) 
VARIABLE GRABPTR 

€ “Handle” to the graphics buffer ) 
VARIABLE GRABU 


€ I had some problems using the Forth definition of 
-Leunch in my programs. This works... ) 
CODE LAUNCHIT 
MOVE.L (A62,A8 С Parameterptr is in the stack ) 


-LAUNCH € Launch with parameters at AQ ) 
RTS ( We should never arrive here! ) 
END-CODE 


GLOBAL С It is always useful to know A5, so I made 
this definition global. We use it to find 
where the screen is located. A5 points to 
your variables, but it can also be used to 
find quickdraw’s globals. ) 

CODE GETAS 
MOVE.L 
RTS 

END-CODE 

MACH 


A5,-(A6) 


( We examine the stack pointer to see if it is 
located on the alternate buffer. ) 
CODE СЕТАТ 
MOVE.L 
RTS 
END-CODE 
MACH 


AT,-(A6) 


( This code does not work on “Мас” with non-standard 
Screen resolution. Using the second buffer is not 
portable anyway. We clear the screen to black. ) 

CODE ClearBuf С ADDR ) 


MOVE.L — (A60*,A0 
MOVEQ.L 8-1,00 € Blacks-1, White=0 ) 
MOVE.W #341,D1 € 342 rows) 

@1 MOVE.L DØ,CAO)+ C 16*4 bytes*8 bits ) 
MOVE.L DB,CAB)+ € =512 pixels) 
MOVE.L 00,(А00% 
MOVE.L 00,(А00% 
MOVE.L 00,(А00% 
MOVE.L DO, CAQD* 
MOVE.L DØ, CAQD* 
MOVE.L 00, САд)+ 
MOVE.L 00,(А00% 
MOVE.L 00, CAØ)+ 
MOVE.L 00,(А00% 
MOVE.L 00, CAQD* 
MOVE.L 00,(А00% 
MOVE.L 00,(А0) 
MOVE.L 00, САб)+ 
MOVE.L 00, CAG)+ 
DBRA 01,61 
RTS 

END-CODE 


С Change the video screen bit and report 
the currently visible video page. 
ø= Alternate 
1= Primary ) 
GLOBAL 
CODE OTHERPAGE С - ThePage ) 
MOVEA.L VIAq, Аб 
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LEA — $1E00(A02,A0 ( Buffer А) 
MOVEQ.L 81,00 
BCHG 86, (AB) ( Bit 6=Page) 
BEQ.S 61 
MOVEQ.L 80,00 

e1 MOVE.L D0,-(A6) 
RTS 

END-CODE 


С Show the other buffer. 

This word always ends drawing. ) 
GLOBAL 
: SHOWB OTHERPAGE DROP ; 


e^ 


Stardraw stores the address of the 
current buffer in GRABPTR. SCREENMEM 
always points to the normal screen. 
It then cleers the invisible buffer. 


Call startdrew when you begin drawing 
on the screen. ) 

GLOBAL 

: STARTDRAW 

VIA 6 VIABUFA + Се VIDEO2 AND 

IF -32768 ELSE @ THEN 

SCREENMEM @ + DUP GRABPTR ! CLEARBUF 


д 


GLOBAL 

: GOFORTH 

С If we have the options we want ) 

CURPAGEOPTION we IF 

( See if we really have the other buffer. 
The stack may still be there. ) 


СЕТАТ 
GETA5 e 122 - 6 32768 - > 
С False=stack is not in the way ) 


ELSE -1 € We don't have the option we want ) 
THEN 


IF € Set the cache off, but do not copy 
the result into paremeter RAM. ) 

SYSPARAM 18 + W@ -33 AND SYSPARAM 18 + W! 

С Pad contains the parameters ) 
-1 PAD 4+! С-1 is alternate screen & sound ) 
CURAPNAME PAD ! 
PAD LAUNCHIT С never goes beyond this point...) 
THEN 
( We finally have the options we wanted. Restore 

the cache setting from the clock chip RAM. ) 

CALL INITUTIL DROP 


2 


ex 


INITBUF gets the correct page option then 
finds the location of the primary screen 
by looking at ScreenBits. The address 
is found at – 122СА5). It then stores а 
pointer to grabptr in grebu. GRABU is 
used in my drawing routines. ) 
GLOBAL 
: InitBuf 
GOFORTH € Get the alternate page ) 
GETAS @ 122 - @ SCREENMEM ! 
GRABPTR GRABU ! 
STARTORAW 


€ UpdateScreen should be called whenever you want 


to show the results on the screen. Usually SHOWB 
would swap screens if you used 2 buffers. In the 
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the other version, it does а ShowB. 
Here, it is does nothing ) 
GLOBAL 
: UpdateScreen ; 
MACH 
С *** end of alternate screen-dependent part *** ) 


ANEW STARFLIGHT 
ONLY FORTH DEFINITIONS ALSO MAC ALSO ASSEMBLER ALSO FORTH 


GLOBAL 

CODE ZPSET C X Y ) 
MOVE.L (A6)+,D1 
MOVE.L (A6)*,D0 


— r 
<< 


MOVEA.L GRABU, А0 
MOVEA.L CAO), AG \ Grabu is а handle! 


ASL.W 46,01 X Row=64*Y -> 64 BYTES/ROW 


MOVE.W 00,02: \ column-X/8 
LSR.W — "3,02 


AND.B 87,08 V Bit=NOT(x and 7) 
NOT.B DØ 


ADD.W 02,01 V addr=basetrowtcolumn 
BCLR 00,(А0,01.М) 


END-CODE 


Global 

CODE 1+ 
ADD.L 06,(А6) 
RTS 

END-CODE 

MACH 


Global 
MOVE.L (A6)+,D0 


MOVE.L (A6),D1 
DIVS.W 00,01 


EXT.L DI 
MOVE.L 01, (Аб) 
RTS 

END-CODE 


\ Originally written by Mike Morton for Mactutor 
\ Translated to Mach 2 by Juri Munkki 


\ constants 
140 constant NumStars 
256 constant MaxX 
172 constant MaxY 
8 constant Мах2 (really is 2^8 ) 
256 constant Xcen 


172 constant Үсеп 


342 512 rect MyBits 

\ variables 

variable zr Numstars 2* 4 - vallot 
variable xr Numstars 2* 4 - vallot 
variable yr Numstars 2* 4 - vallot 
variable speed 


: MekeSter ( ster -really 2 * index ) 


CALL Random МахХ Mod xr ster + W! 
CALL Random MaxY Mod yr ster + W! 


1 MaxZ scale zr ster + W! 


; 
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: MoveStars 
NumStars 2% 0 do 
zr i + w@ L Ext ® if 
хг 1+ wê L_Ext MaxZ scale zr 1+ мё w/ Xcen + 
yr 1+ wê L_Ext MaxZ scale zr 1+ иё w/ Үсеп + 
2dup ped w! pad 2* w! 
pad @ myBits call ptinrect 
if ZPSET zr i+ w@ Speed @ - zr i* w! 
else 2drop i MakeStar then 
else i MakeStar then 
2 *loop 


s 
: Initialize 
NumStars 2* Ø do 
i MakeStar 
2 *loop 


: DoStars 
call hidecursor 
Initialize 
begin 
StertÜrew 
eMOUSE -20 SCALE 0 MAX SPEED ! 
MoveStars 
ShowB 
call button if 
call tickcount 
begin 
@MOUSE -20 SCALE 0 MAX SPEED ! 
MoveStars UpdateScreen 
call button Ø= until 
call tickcount swap - 5 < else Ø then 
until 


begin otherpage until 
call showcursor 


: GoStars 
Ini tBuf 

DoStars 

Bye 


д 


Listing 2: Changes necessary for alternate screen 
version 


HEAPVAR GraBu 
ANEW GRAPHICS_BUFFER 


ONLY FORTH DEFINITIONS DECIMAL 
ALSO MAC ALSO ASSEMBLER ALSO FORTH 
VARIABLE GraBu 0 GRABU 1 
VARIABLE SCREENMEM 
GLOBAL 
CODE GETAS 

MOVE.L А5, -САб) 


CODE ClearBuf С ADDR ) 
MOVE.L — (A6)*,A0 
MOVEQ.L 8-1,00 
MOVE.W — "341,01 

@1 MOVE.L 00,(А00% 
MOVE.L 00, CA@)+ 
MOVE.L 00, CA@)+ 
MOVE.L 00, CAG)+ 


MOVE.L 00, (А0 
MOVE.L 00, CAG)+ 
MOVE.L 00, CAD)+ 
MOVE.L 00, CAG)+ 
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MOVE.L 00,(А02% 
MOVE.L —D0,CAQD* 
MOVE.L —D8,CAQD* 
MOVE.L —D0,CAQD* 


MOVE.L 00,(А00% 
MOVE.L D@,CA@)+ 
MOVE.L —D0,CAQD* 
MOVE.L —DO,CA2D* 
DBRA 01,61 
RTS 

END-CODE 


GLOBAL 
VARIABLE FULLSCREENPORT 
VARIABLE DRAWINGPORT 
0 0 342 512 RECT FULLSCREENRECT 
( We initialize the grephics buffer to 
hold 512*342, although we do not know 
that the screen is just that size. ) 
: InitBuf 
512 342 8 */ CALL NEWHANDLE DROP GreBu ! 
GRABU @ CALL HLOCK DROP 
GETA5 6 122 - 6 SCREENMEM ! 
С Open а port for ShowB 
This is not necessary when you use version 1 
of showb. ) 
112 CALL NEWPTR DROP FULLSCREENPORT ! 
112 CALL NEWPTR DROP DRAWINGPORT ! 
FULLSCREENPORT & CALL OPENPORT 
DRAWINGPORT 6 CALL OPENPORT 
GRABU @ @ PAD ! 
64 PAD 4 + W! 
0 0 342 512 PAD б + !RECT 
PAD CALL SETPBITS 


GLOBAL 


: STARTDRAW 
GRABU @ @ CLEARBUF 


2 


GLOBAL 

( This is definiton 1 of showb. It is not compatible 
with nonstendard screen resolutions. You cen use 
this version while debugging programs on а Mac. 

: SHOWB 

GRABU @ @ 21888 SCREENMEM 8 CALL BLOCKMOVE DROP 


MP 

С This is definition 2 of showb. It uses CopyBits and 
is thus works with апу computer that has Quickdrew.) 

: SHOWB 

DRAWINGPORT @ 2* FULLSCREENPORT @ 2+ ( BitMaps ) 

DRAWINGPORT 6 8 + DUP С Rects-512*342 ) 

Ø С SrcCopy 2 Ø С No region ) CALL COPYBITS 


( Since we only display the normal grephics page, 
otherpage should always return 1 ) 

GLOBAL 

1 CONSTANT OTHERPAGE 


С UpdateScreen is called when you want to show 
the results on the screen. Usually SHOWB would 
swap Screens if you used 2 buffers. In the 
2 buffer version, updatescreen does absolutely 
nothing. Here, it does а SHOWB. ) 

GLOBAL 

: UPDATESCREEN 

SHOWB 
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Forth Forum 
FKeys & Events 


FKEYs and Events 


The example we'll deal with this time has some history. On 
a national bulletin board here in France, Calvacom, which has a 
large section of its activity devoted to the Mac, a proposal was 
made to write an FKEY that would paste one of a number of 
character strings into the application currently under use. Thus 
one would have an easy way to enter ‘boilerplate’ phrases or 
often used commands into text processors, terminal emulators 
etc. 

I thought this would make a nice example for the Forth 
column, especially since we hadn't had an FKEY dealt with yet. 
In the way of writing this, I discovered several things. First, the 
simple strategy that comes to mind - taking a string that was 
saved away somewhere and posting key down events for one 
character after the other - works only in certain cases, so one has 
to go a more complicated way (as you'll see soon). Second, 
somebody had of course in the meantime written the FKEY under 
question - in some other language. Nevertheless, still a good 
Forth example. 


Implementing an FKEY 


Everyone of you has probably already used one or the other 
function key, that is, command-shift-number combination. Some 
might even have written one, its implementation being rather 
simple. The FKEY resource is a simple subroutine with its entry 
pointat the beginning of its code. It is called from the routine that 
handles the keyboard. If that routine detects a command-shift- 
number combination, it will look for the FKEY resource corre- 
sponding to the number, and if such aresource is present, load and 
execute it. 

No parameters are passed to the FKEY routine on the stack; 
we'll simply set up a local Forth stack on entry to the routine, 
using LINK, save all registers away, then call the main body of 
the FKEY, and finally restore the registers and UNLINK A6. 
This is the standard glue routine for writing kernel-independent 
Mach2 code which you might already be familiar with. See 
listing 1. 

[One remark withregard to the listing here. This program has 
been written in Mach2.12 which has a different Toolbox call 
mechanism than earlier versions. In particular, it expects D4 to 

point to a common stack low in memory which can be used for all 
toolbox calls. This stack, and D4, are set up in the Mach2 system. 
Therefore, to write kernel-independent code, one has to use the 
old CALL mechanism again. This word is available under a new 
name: (CALL). If you have an older Mach2 version, simply 
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replace all occurrences of (CALL) with CALL, or redefine the 
word]. 


The main body of the FKEY will first look whether it has been 
called from a bona fide application or whether the topmost 
window is a dialog or desk accessory. In the latter two cases, the 
FKEY will do nothing but beep and return. Since the FKEY itself 
might display a dialog (for editing the text strings), it should not 
be allowed to redisplay its own dialog when it is already active. 
Checking whether any dialog is already in place is one way of 
achieving this; you might think up some more sophisticated ways 
and change the program accordingly. 

If the routine has been called from within a good environ- 
ment, it will wait for the next key pressed. If the key is a number 
key, the appropriate message will be posted (see later how this is 
done). If itis the “е” key, a dialog will be displayed for editing the 
text strings. In all other cases the routine will simply beep and 
return. 

Posting Events 


The first problem that we encounter here is how to post key 
down events that correspond to the text string into the event 
queue. Very simple, you'll say, do the following: 


: post.cher € char - ) 3 swap call post.event drop ; 
: post.string € string - ) 
count Ø DO dup i + cê post.char LOOP drop ; 


where 3 is the event code for a key down event, and the event 
message simply contains the character code in the low byte, and 
no key code (=0). Leaving out the actual key code has so far 
caused no problem in any case that I tested. 

Well, the simple example works. In a way. If the string that is 
posted is longer than 15 characters, Mach2 will simply beep 
because it cannot accept more keydown events before switching 
tasks. This doesn't have anything to do with the actual length of 
the event queue or the maximum number of allowed events. It is 
the application that can't deal with so many 'keystrokes' coming 
in rapid succession. In addition, of course, if we don't check the 
event queue before posting an event, we take the risk of losing it 
if the maximum number of allowed events (20 by default) has 
been reached. 

This last number can be changed by editing the boot blocks. 
However, onecan think of a more elegant solution that makes the 
whole process completely independent of the maximum length 
of the event queue. We allow the posting of a character only if the 
GetNextEvent routine fetches a null event. In that case we can be 
sure that not too much activity is going onand the key down event 
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will be handled correctly. 

But how do we handle this process? We cannot do some sort 
of waiting loop within the FKEY, since GetNextEvent will only 
be called by the application after we have returned. Therefore the 
FKEY must install a short background routine that monitors the 
activity of GetNextEvent and posts key down events from the 
string to be transmitted each time a null event is received. Here 
the JGNEFilter system global, already used for several examples 
in MacTutor (V 149, Bob Denny, and V2#6, JL), comes in very 
handy. To post a message into the event queue, the post.string 
word as defined in the listing saves the string and its length away 
into a defined place and then changes the JGNEFilter vector to 
point to a custom routine that will post the keystrokes. 

The custom routine, GNE.glue, calls GNEIntfc through our 
standard glue code, which you really know by now. GNEIntfc 
looks at A1 (which points to the event record), and if a null event 
is about to be transmitted, it will take the next character from the 
saved message string and post a key down event under the 
following conditions: 


1. A certain delay has expired since the last character was posted 
(2 ticks in my example) and 

2. The number of pending events is less than a predefined 
number (here 10). 


When the end of the string has been reached, the filter routine 
resets the JGNEFilter vector to its old value. 

Using the method just described, one can transmit strings of 
arbitrary length to applications. Which is what we wanted. 


Editing the text strings 


If an 'e' is pressed after the FKEY, we'll display the editing 
dialog. The Rmaker source for this dialog (ID=2000 for DLOG 
and DITL, you may want to change this) is in listing 2. It simply 
consists of 10 editable text items, one OK button and some static 
text. 

The associated Forth word, edit.messages, does a number of 
things. It first tries to open a resource file named 
"FKEY .messages' and creates anew one if it doesn't succeed. Ву 
standard, this will be kept in the system folder; leave it there. You 
can prepare any number of files containing standard messages by 
renaming them. 

The routine then gets the dialog with ID 2000 (it is a shame 
that FKEYs cannot ‘own’ resources like DRVRs etc. can). If the 
dialog can't be found, it beeps and returns; otherwise, it displays 
the strings from the FKEY .messages file in the boxes for the 
editable text items. They are 10 individual string-format re- 
sources type *bplt" with ID=3 to 12 (corresponding to the dialog 
items 3 to 12). If the resources cannot be found (i.e. the file has 
just been created and is empty), they are created and initialized 
with whatever was in the EditText items of the dialog box. In my 
case, I used the texts ‘Message x’, but you might just leave the 
strings empty. If the bplt resources are there, they replace the 
EditText items. 
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А ModalDialog is then called, allowing the strings to be 
edited. The only enabled item is the OK button, which returns to 
the Forth routine. Then, the changed text strings are written back 
to the bplt resources in the FKEY .messages file, the resource file 
updated and the dialog disposed of. 

Finally, post.message is the routine that is called when a 
number key is pushed after the FKEY. It gets the bplt resource 
corresponding to that number and calls post.string (described 
above) to transmit the string via the GetNextEvent filter routine. 

make.fkey creates a file ‘fkey.text’ that contains the FKEY 
resource and has the correct type and creator to be opened from 
the FKEY installer (from Quick and Dirty Utilities, Dreams of 
the Phoenix, Inc., P.O.Box 10273, Jacksonville FL 32247, (904) 
396-6952). This file is then packed together with the dialog 
resources into one file. The FKEY may be installed with the 
installer; the DLOG 2000 and DITL 2000 must be copied with 
ResEdit. 

Some last notes 


As you’ ve seen, yet another Mach2 version has been released, 
v2.12, making v2.11 obsolete only two weeks after I received it. 
No BIG modifications, only minor ones. 

Ireceived some comments from a reader, James Merkel, who 
mentioned that it would be a good idea for Palo Alto Shipping to 
release the source for the multitasking kernelas well, now that we 
have the source of the I/O task. The second comment was to 
release bug fixes in MacTutor as well as on GEnie, for those not 
having access to the GEnie Roundtable (including myself). Very 
good suggestion. PAS, do you listen? 

Last, the bulletin board that I mentioned, Calvacom, is now 
accessible via Tymnet from the US. If you'd like to see what's 
going on over here or want to leave me some mail, connect 
yourself to a Tymnet line and type ‘CalvaCom’ at the login 
prompt, then ‘nouveau’ when it prompts you for your access 
code. Youcan subscribe with your credit card, as usual. Speaking 
some French helps, of course, but most anybody on the board will 
understand English. Connect charges (overseas rates included) 
are of the order of $25 per hour. I'd like to see your feedback in 
my mailbox! 


Listing 1: Mach2 FKEY for text glossary 
С *** Function Key exemple. JL June 1987 *** ) 
ONLY FORTH ALSO ASSEMBLER ALSO MAC 


4ascii 0015 CONSTANT “qd 15 
4ascii bplt CONSTANT “bplt 
4ascii DITL CONSTANT "diti 
4ascii DLOG CONSTANT “dlog 


2 CONSTANT post .delay 
( 2 ticks wait between posting of characters ) 
10 CONSTANT max.event 
( max ® of pending events allowed during posting ) 
$148 CONSTANT EvQHdr 
$294 CONSTANT JGNEFilter 
2 CONSTANT QHead 
6 CONSTANT QTail 
BINARY 000000000000 1000 CONSTANT KeyEvent 
DECIMAL 
( heeder code filled at end of definitions ) 
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header start 


JMP start С to be filled later ) : post.message ( msg! | dh dPtr tPtr - ) 
header temprect 8 allot * FKEY.messages^ (call) OpenResFile (call) UseResF ile 
header itemrect 8 allot *bplt msg* 3 + (call) getResource -» dh 
header myEventRec 16 allot dh IF dh @ post.string 


ELSE beep THEN 
: beep 5 (са11) sysbeep ; 


2 


CODE cmove ( redefine since this is part of Kernel ) : edit.messages 
MOVE.L CA62*,D0 ( | dPtr itemType item box box! itemHit thandle refnum - ) 
MOVE.L CA6)+,A1 * FKEY.messages^ dup (call) OpenResF ile 
MOVE.L (A62*,A0 (call) ResError 
TST.L DØ IF drop dup (call) CreateResFile 
BLE.S e2 (call) OpenResFile dup -> refNum 
61 MOVE.B СА@)+,(А1)+ (call) UseResF ile 
SUBQ.L 81,00 ELSE dup -? refNum 
BNE.S 61 (call) UseResFile drop 
@2 RTS THEN 
END-CODE getFkey0lg -> dPtr 
dPtr IF 
:4w/ ; 13 3 DO 
dPtr i ^ itemType ^ item ^ box 
: getFkeyDig (call) GetDItem 
2000 0 -1 (call) GetNewDialog item (са11) HLock drop 
; *bplt i (call) GetResource -> thandle 
thendle IF 
: events EvQHdr QTail + 6 EvQHdr QHead + ё - 22 / ; thendle (са11) HLock drop 
item thendle 6 (call) SetIText 
: post.char ( char - ) 3 swap (call) postEvent drop thandle (call) HUnlock drop 
: ELSE 
256 (call) NewHandle drop 
header SavedJGNEFilter 4 allot "bplt i " Message” (call) AddResource 
header SavedString 256 allot THEN 
header bytesToTransfer 4 allot item (call) HUnlock drop 
header lastpost 4 allot LOOP С all messages have been initialized ) 
: GNEIntfe (| btt - } Ø ^ itemHit (call) ModalDialog 
getA1 wê Ø= IF 
(71 bytesToTrensfer 8 -> btt 13 3 DO 
btt IF (call) tickcount 17 lastpost 6 - post.delay > dPtr i ^ itemType ^ item ^ box 
üevents max.events < AND (call) GetDI tem 
IF item (call) HLock drop 
[^] SavedString dup c@ btt - 1+ “bpit i (call) GetResource -> thandle 
+ cê post.char thandle IF 
btt 1- ['] bytesToTrensfer ! thandle (call) HLock drop 
(са11) tickcount [^] lastpost ! item thandle @ (call) GetIText 
THEN thendle (call) ChangedResource 
ELSE thandle (call) HUnlock drop THEN 
[^] savedJGNEFilter 6 JGNEFilter ! item (call) HUnlock drop 
THEN LOOP ( all messages have been updated ) 
THEN refNum (call) UpdateResF ile 
р dPtr (call) DisposDialog 
CODE GNE.glue ELSE beep THEN 


LINK A6,#-256 С 256 bytes of local Forth stack ) 
MOVEM.L АЙ-А5/00-07,-САТ) (€ save registers ) 


; 


( по need for loop return stack ) : fkey ( | keycode - ) 
( no parameters are passed ) (call) frontwindow windowkind + иё 1_ех{ dup 
JSR GNEintfcC call Forth routine ) 2 = swap 0< OR 0= IF 
MOVEM.L (А72%,Ай-А5/00-07 С restore registers ) BEGIN 
UNLK Аб KeyEvent ['] myEventRec (call) GetNextEvent UNTIL 
LEA SavedJGNEF ilter, Ad 
MOVE.L (АЙ),АЙ С return address ) [*] myEventRec message + 6 $FF and -> keycode 
JMP САЙ) keycode ascii e = 
END-CODE IF edit messages 
ELSE 
: post.string ( string | length - ) keycode ascii Ø < keycode ascii 9 > OR 
string cê -> length IF beep ELSE keycode 48 - post.message 
string [^] SavedString length 1+ cmove THEN 
length [°] bytesToTrensfer ! THEN 
(call) tickcount [^] lastpost ! ELSE beep 
JGNEF ilter 8 [^] SavedJGNEFilter ! THEN 


(71 GNE.glue JGNEFilter ! 


( *** our standard glue routine *** ) 
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CODE fkey.glue 
LINK А6,8-2048 С 2K bytes of local Forth stack ) 
MOVEM.L Аб-А5 /00-07,-САТ) С save registers ) 
MOVE.L Аб, АЗ ( setup local loop return stack ) 
SUBA.L #256,A3 € starting 256 bytes below locals ) 
( no parameters are passed to the FKEY ) 
JSR fkey С call Forth routine ) 


MOVEM.L (А72%,А0-А5/00-07 С restore registers ) 

ОМК Аб 

MOVE.L (А72%,А0 

JMP САД) 
END-CODE 


( return address ) 


header end 


С install initial jump vector 2 
' fkey.glue * start 2+ - ' start 2+ w! 


( *** installation *** ) 


: make.fkey ( | refNun namePtr - ) 
* fkey.text^ dup $create-res 
abort” You hav e to delete the old ‘fkey.text’ file first.” 
$open-res dup -> refNum call UseResF ile 
(*] start [^] end over - call PtrToHand drop С result code ) 
«(кеу 5 * Mach2 FKEY^ call AddResource 
refNum $close-res drop ( result code ) 
Ø * fkey. text” 
getvol ioVRefNum + w8 1.ext 
getfileinfo drop 
«4815 “fkey * fkey.text^ setfileinfo 


Listing 2: Rmaker file for the FKEY 


* File fkr.R 
Mach2 Fkey 
FKEYQD 15 


Include Fkey. Text 


Type DLOG 

‚ 2000 
New Dialog 
30 14 330 494 
visible goAway 
1 


0 
2000 


Type DITL 
‚2000 
22 


BtnItem 
256 32 278 91 
OK 


StaticText 
256 136 286 463 
Text FKEY € 1987 J. Langowski/MacTutor Written in Mach2™ Forth 


EditText Disabled 
8 32 24 464 
Message 9 


EditText Disabled 
32 32 48 464 
Message 1 


EditText Disabled 
56 32 72 464 
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Message 2 


EditText Disabled 
80 32 96 464 
Message 3 


EditText Disabled 
104 32 120 464 
Message 4 


EditText Disabled 
128 32 144 464 
Message 5 


EditText Disabled 
152 32 168 464 
Message 6 


EditText Disabled 
176 32 192 464 
Message 7 


EditText Disabled 
200 32 216 464 
Message 8 


EditText Disabled 
224 32 240 464 
Message 9 


StatText 
8 8 24 28 
0 


StatText 
32 8 48 28 
1 


StatText 
56 8 72 28 
2 


StatText 
80 8 96 28 
3 


StetText 
104 8 120 28 
4 


StatText 
128 8 144 28 
5 


StatText 
152 8 168 28 
6 


StatText 
176 8 192 28 
7 


StatText 
200 8 216 28 
8 


StatText 
224 8 240 28 
9 


‹—. 


sel 


A 
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Forth Forum 
Hierarchical Menus from Forth 


Feedback dept. 


We got some interesting reader's comments again, so before 
moving on to the main topic, I'llopen my mailbox. The first letter 
comes from Sweden, I got it after having sent off the September 
column, and here's someone who can read thoughts: 


*...I have used MacForth (level 1), NEON and I am now 
using MACH2, mainly as an instrument for trying out assembler 
subroutines and algorithms. 

I found MacForth rather disappointing, it simply hides too 
much of the Mac environment and consequently you have to 
learn far too many special words. That could also be said of 
NEON of course, but this was a special case. I found the object 
oriented environment quite fascinating. I deliberately use the 
past tense, I have heard nothing from Kriya after the launching of 
the Mac Plus, NEON support seems to have stopped. MACH on 
the other hand is an excellent compromise, almost pure Forth, a 
reasonable Mac user interface, a very fine assembler and - a 
disassembler. 

That brings me to the actual point of this letter, a suggestion 
for your MacTutor column. Dan Weston mentions FKEYs in his 
fantastic books but only in passing. So, I wanted to take a look at 
one of the regular ones in the system file. Lacking Nosy or 
anything similar, Iopened FKEY 3 with ResEdit and transferred 
the data to my MACH editor. The data was then converted to 
DC.W strings and loaded into MACH. You can see the result of 
the disassembly in the enclosed copies. I believe it was worth the 
trouble, there seems to be quite a bit of interesting code there. 

There ought to be a simpler way of doing this however, a small 
MACH program should make it easier to peek at code on disk and 
perhaps even in ROM. I could always buy NOSY of course, but 
I still think this is a rather nice idea for a MacTutor article!” 

Bertil Holmberg 

Malmö, Sweden 


Well, Bertil, you' ll have been pleased to see that FKEYs have 
actually been treated in last month' s column. As to the disassem- 
bly problem, I think that your way of doing it is actually rather 
efficient, if one does not want to use Nosy. Another way to go 
would be to do a GetResource on the interesting piece of code 
(DRVR, FKEY, МРЕЕ, etc...), get the address from the handle 
and then do a disassembly from Mach2 on the code block, using 
the IL word. 

Another long letter deals with Mach2 features, and some 
bugs: 


“I read your comparison of Mach2 and MacForth Plus in the 
April 1987 issue of MacTutor with great interest. Ihave used both 
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Jórg Langowski 
0 MacTutor Editorial Board 
f Grenoble, France 
miniterm MacTutor Vol. 3 No. 10 


| e| Terminal 
| Rate фр 
E format , XT 


Parity : 6 date 
Handshake ? data 
Quit 


node EMBL 
xj, 6-ҒМО-198?7 18:00» 


(m data 
1 stop 
Password: 
T & 1.5 stop 
: Last interocti( Y2 Stop 


Fig. 1 Miniterm example with hierarchical Menus 


systems and tend to agree with your conclusions. I particularly 
like two features of Mach2: the uniform toolbox access using 
CALL and the standard Motorola assembler syntax. I think in 
summary that the Mach2 system is more oriented towards the 
Macintosh and the 68000 than is the MacForth system. 

I recently received the latest update to Mach2 (v2.11) [ok, it’s 
2.13 asI write this - JL] from PASC that contains the integrated 
editor and several bug corrections. Unfortunately there are sev- 
eral bugs in the new system also. Specifically I noted the 
following: 

(1) Editor 

The editor leaves a lot to be desired - not the least of which is 
the single open window and 32K limitation (like MockWrite). ... 
It seems to me that this editor is only useful for single standalone 
files. For other situations I still use Edit2.1. 


[Well, I must agree with your comments there. It is a shame 
that a powerful development system like Mach2 still lacks a 
reasonable integrated editor. At least multiple windows should 
be possible, and an MPW-like ‘worksheet’ conception, with 
command executionfrom within the Editor, would be really nice. 
When is someone going to port the excellent Sibley editor from 
MacForth into the Mach2 environment? My standard develop- 
ment systemis Mach2.13 withits editor and MockWrite, plus Edit 
under Switcher if required. JL] 


(2) IOTASK 

The new system provides the source for the IOTASK code 
and allows you to replace the IOTASK with your own custom 
IOTASK. ... The IOTASK code needed to be modified in three 
places: (RUN-GROW) and (RUN-DRAG) do not have reason- 
able limits - you can shrink the window to a line and drag it off 
the screen. Also in (RUN-GROW), the window contents are 
erased if the window is made smaller [this has been fixed in 2.13 
- JL]. I modified the IOTASK in these three areas and success- 
fully replaced the IOTASK. 

Another minor thing I noticed in the IOTASK code is that 
there is a location reserved at the end of the EVENT-RECORD 
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for an empty menubar handle i.e.: 
: EmptyMenuBar ( - a) EVENT-RECORD $1Е ғ; 


If your application has only one menubar, but multiple 
windows, you could place a handle to your menubar in this 
location as follows: 


MBarHandle (9 EmptyMenuBar ! 
where MBarHandle is a handle to your menubar 


then your menubar will always be present no matter which 
window is active. One of the things I didn't like about the way 
Mach2 applications ran was that if you clicked in a window 
without a menubar a blank menubar resulted. The above words 
(including the EmptyMenuBar word) should be placed in your 
application code, not in the IOTASK code. 

Now that we have the IOTASK source, wonder if we could 
get PASC to provide the multitasking Kernel source? [Let's 
hope... JL] 

(3) The infamous 8 byte record from Quickdraw 

I think this bug fix was well worth the update all by itself. 
There were several parts of my application that always crashed 
for unknown reasons when I tried to execute them in the interac- 
tive mode (but strangely enough did not crash or crashed very 
seldom after turnkeying). With this new version of Mach2 the 
crashes are gone. Therefore I would conclude that the use of the 
common stack area and the register exchange D4 <-> A7 before 
and after calls to the Toolbox fixed these problems. 

I assume that you also have to include the register exchange 
lines of code in any assembler code where you call the toolbox 
[see this month's example - JL]... 

One might ask whether the register exchange needs to be 
made for toolbox calls that are register based - i.e. ones that don't 
use A7. However, many toolbox calls themselves make calls to 
other toolbox routines. Therefore, the safe approach seems to be 
to always put in the register exchange instructions. 

(4) Subroutine stack space 

The notes with the new Mach2 system state that you can make 
the subroutine stacks smaller (i.e. 1K rather than 8K) provided 
that there are no calls to LOADSEG after your program starts to 
run. I reduced the size of all my task subroutine stacks from 8K 
to 1K and the application appears to run OK. I am pretty sure that 
there are no calls to LOADSEG after the program is first 
initialized since I explicitly call initialization routines in all 
segments (so they all should be loaded at program startup). 

I understand from PASC that they have a fix that avoids this 
problem - i.e. LOADSEG can be allowed with only 1K subrou- 
tine stacks. They will put this fix on GEnie RoundTable - 
however I think it would be worthwhile to publish this fix in 
MacTutor for those of us not on GEnie. [This fixis part of Mach2 
v.2.12 and later; itis also containedon the source code disk. Iam, 
however, checking how I can get access to GEnie from overseas 
- JL] 


502 


Other comments: 


(1) Global variables 

This does not have anything to do with the new Mach2 update 
but is just something I didn't know. All variables are Global - i.e. 
you can access any variable from any segment without declaring 
it as global [this is logical since variable addresses are taken as 
offsets from A5, not PC-relative - JL]. The same is true of a 
constant. I'm not sure about CREATE though - is an array 
definedby CREATE globally accessible? [No. Any word defined 
within the segment space will not be globally accessible unless 
GLOBALized beforehand. This is true for colon definitions as 
well as for CREATE - JL]. 

(2) TMON 

You mentioned in your April 87 MacTutor article that you 
used TMON for debugging Mach2 code. I tried TMON and was 
able to get into it ok (by using the interrupt switch), however 
when I attempted to get back to my application via Exit, TMON 
bounced me right back to the debugger screen with an illegal 
instruction. How do you get back to the application from TMON? 
[This error has not occured іп any of my tests, sorry. 2.11 to 2.13 
seem to work OK with TMON. Check the value of the DEBG 
resource in your Mach2 application. It should be =2 to make 
Mach2 collaborate with TMON - JL]. 

(3) Multitasking code 

I have noticed that assembler code for the 68000 is not much 
more difficult to read than some high level languages. (In 
particular, I think that C is more cryptic than assembler level). 
[Aha! How about Forth? - JL]. However, if we want to write a 
multitasking application in assembly, we need a multitasking 
shell. Therefore I think a good article for MacTutor would be a 
multitasking shell written in assembly. It probably would not 
have to be as extensive as the Mach2 multitasker since it would 
be used for stand alone applications only. /Well, here's an 
interesting task for our assembler specialists... submissions 
welcome - JL]. 

Well, that's all I have to say for now - keep up the good work 
in MacTutor. I find something useful in almost every month's 
edition." —James J. Merkel 

[Thanks for these interesting comments on Масћ2. I think 
PASC will have responded before you even read this...] 


Hierarchical Menus 


After this question-and-answer session, we'll treat a subject 
that is closely connected with the new System 4.1 / Finder 5.5 
release. The new system contains a new menu manager, which 
supports hierarchical menus. These are menus which can contain 
submenus associated with a menu item. 

How does a hierarchical menu show up on the screen? Fig. 1 
shows an example; the main menu item is followed by a small 
arrow, and if you leave the cursor on the item for some short time, 
the submenu appcars to the side of the main item. Then, you can 
select an item from the submenu as usual. 


Hierarchical menus can make the menu setup much more 
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compact, and are therefore of great advantage if you have a lot of 
parameters that you want the user to change - like in a telecom- 
munications program where you adjust baud rates, data formats 
and the like. 

There is a certain procedure which you have to follow if you 
want to make use of such menus. I have implemented this 
procedure in Mach2, using the ‘dumb terminal’ program from the 
Mach2 example disk as a skeleton. The example will create a 
stand-alone terminal program which supports desk accessories 
and allows selection of parameters through a hierarchical menu 
as in Fig. 1. 


Creation of submenus 
The requirements for using hierarchical menus are: 


- 128K (or larger) ROMs; 

-amenu definition routine with version number 10 or higher; 

- the new menu manager (System 4.1 or higher); 

- and the availability of the traps GetItemCmd ($A84E) and 
SetItemCmd ($A84F), these also being installed in System 
4.1 or the 256K ROMs. 


Second, there are some recommendations as to the use of 
hierarchical menus. Those menus, sub-menus, sub-sub-menus 
and so on may be nested up to 5 levels deep. There is actually a 
very instructive demo application floating around in network 
space that fills up the menu bar with a whole lot of hierarchical 
menus, one of which has the ‘quit’ command hidden in its deepest 
level. When you've finally managed to find it, you'll know why 
it is recommended not to use more than one menu sublevel... 

Also, the commands in a sub-menu should be all of a similar 
group, So for instance, the settings of a certain parameter, 
predefined macros, text styles, etc. 

What is a submenu? It is created like a regular menu, with its 
menu ID, title, and items. You can create its menu handle from 
a resource with GetMenu, or use NewMenu to create it from 
scratch. Once you have the handle, the call to JnsertMenu 
determines whether it is inserted into the menu bar or stays 
"hidden' for being displayed as a sub-menu. For sub-menus, 
you'll have to call InsertMenu with beforelD = -1. 

The submenu is then attached to a menu item in the following 
way: 


- the йетСта field of the menu item (that which contains the 
keyboard equivalent) has to contain $1B. 

- the itemMark field (where the check mark character is kept) 
has to contain the ID of the submenu; since this field is one 
byte wide, this means that the submenu may never have an 
ID greater than 255. 

Once these two conditions have been fulfilled, and the menu 
has been inserted in the proper way, the item of the main menu 
will contain the little arrow pointing to - and displaying - the 
submenu. Selectionscan be made in the submenu, and the routine 
MenuSelect will return the proper menu ID and item number. 
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Implementing the submenu in Forth 


The example, Listing 1,is written in Mach2. The trick is that, 
even though menu handling is done on a level *hidden' from the 
basic Mac interface, the system allows a menu insertion with 
beforelD = -1. This is done in the bounds parameter of the menu 
description. The trap $еШетСта has to be redefined; notice the 
stack exchange D4 <-> A7 that is done before and after the trap 
call. 

A submenu that has been properly created (by using -1 
menuID menu BOUNDS) may then be inserted as a branch of 
a hierarchical menu with the word branch. The parameters are: 
the submenu ID, the main menu ID, and the ID of the item to 
which the submenu will be attached. branch first checks whether 
hierarchical menus are allowed, and if so, changes the itemMark 
and itemCmd fields of the main menu item so that it points to the 
submenu. 

Therestof the listing isa terminal program which mightcome 
in handy as a skeleton for a more powerful telecommunication 
utility (you might for instance add some of the XMODEM 
routines that I described earlier). 

The Apple menucontainsan About... item which will display 
an alert with ID=128 if present in a resource file. Our double- 
clickable version on the source code disk contains such an alert. 
If you don't have that disk, get it, or create your own alert. 


One last word 


The ‘hacker story’ that I put in two months ago has created a 
lot of heated discussion with regards to the ethics of software use, 
licensing agreements, copy protection and the like. [As I write 
this I have not read any letters to MacTutor regarding this issue, 
but I’m sure they will come]. Most of the ‘ethics’ discussion, 
however, was not really to the point. The story was written from 
the *MacTutor Europe Branch’ point of view and meant as one 
example of the situation of software users vs. publishers on this 
side of the Atlantic. Namely, this situation still leaves a lot room 
for improvement. Major points are that copy protection is still 
considered normal here, software prices are comparatively high 
and support comparatively low, and many users are getting less 
than mediocre service without even realizing. A couple of us are 
at present organizing a group that will try to improve the relations 
between the three parties in the software business - developers, 
publishers, and users. This would mean in particular improving 
the flow of information (which product does what, has which 
bugs, can/cannot be recommended; getting bug reports back to 
developers and responses back quickly to users; reasonable 
update policies, etc.). As soon as this project gets out of the 
planning phase, I'll tell you more about it. 


Listing 1: 
Exemple terminal progrem using hierarchical menus 


\ routines for hierarchical menu support in Mach2 
\ J. Langowski / MacTutor July 1987 


\ The terminal emulation routines contained here have origi- 
nally 
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X been created by Palo Alto Shipping Co. as an example on 
their 

X Mach2 distribution disks. The code has been somewhat 

\ modified to integrate with the hierarchical menu example and 
\ to form a stand-alone application. 


only forth also assembler also mac also i/o 


108 USER TaskMenuBar 
164 USER goaway-hook 


$40444546 CONSTANT "mdef 
$44525652 CONSTANT *drvr 


$28E CONSTANT ROM85 
$B5C CONSTANT MenuMor Type 
$A89F CONSTANT undef Trap 


( *** menu record data structure *** ) 
Ø CONSTANT menuID С integer ) 
2 CONSTANT menuWidth C integer ) 
4 CONSTANT menuHeight С integer ) 
6 CONSTANT menuProc С handle ) 
10 CONSTANT enableFlags € longint ) 
14 CONSTANT menuData С Str255 and other data ) 
( *** menu Data format *** ) 
( counted string: menu title ) 
( followed by 1 to 31 times: ) 
С counted string: menu item ) 
( byte: item icon 8 ) 
С byte: equivalent character ) 
С byte: check mark character ) 
С byte: text attributes ) 
D 
( end: zero byte. ) 


CODE setitemcnd 
EXGD4,A7 
MOVE.L 8CA6),-CAT) 
MOVE.W бСАб), -САТ) 
MOVE.W 2САб), -CAT) 
ADDA .W 8%С,Аб 
-Set I temCmd 
EXGD4,A7 
RTS 

END-CODE 


CODE getitemcmd 
EXGD4,A7 
MOVE.L 8CA62,-CA7) 
MOVE.W 6CA62, -CATD 
MOVE.L (A62,-CAT) 
ADDA.W 8%,А6 
-get I temCnd 
EXGD4,A7 
RTS 

END-CODE 


: newrom? rom85 wê l ext 05 ; 
: newnenus? MenuMgrType ё -1 <> ; 


: getI temCmd? 
$A84E call gettrapaddress undef Trap call gettrapaddress <> ; 


: MDEF-version “mdef Ø call getresource 8 10 + wé ; 


: branch.menu ( subID mainID item | mainmenu submenu - } 
newrom? 
newmenus? AND 
getItemCmd? AND 
MDEF-version 9 > AND 
IF mainID call getMHandle -> mainmenu 
mainmenu @= abort” Main menu does not exist” 
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subID call getMHandle -> submenu 

submenu Ø= abort” Submenu does not exist” 

mainmenu item! subID call setitmmark 

mainmenu item? $18 setItemCmd 
ELSE 

1 abort” System does not support hierarchical menus” 
THEN 


2 


Variable baud? 
Variable data 
Variable stop! 
Variable parity” 
Variable hsk? 
Variable DAName 


400 8000 terminal EMULATOR 

NEW.WINDOW TERM 

“ Terminal” TERM TITLE 

45 25 335 475 TERM BOUNDS 

DOCUMENT VISIBLE GROWBOX CLOSEBOX TERM ITEMS 


NEW.MBAR TermMenuBar 


200 CONSTANT Apple_ID 

create epple.string $01 c, $14 с, 

МЕН МЕМ) Apple.menu 

apple_string Apple menu TITLE 

0 200 Apple menu BOUNDS 

* About Terminal..;(-” Apple_menu ITEMS 


3090 CONSTANT Term. ID 

NEW.MENU Term menu 

* Terminal^ Term menu TITLE 

0 Term ID Term_menu BOUNDS 

” Rete;Format;Perity;Handsheke;Quit^ Termunenu ITEMS 


129 CONSTANT baud_ID 

NEW.MENU baud_menu 

* Rate” baud_menu TITLE 

-] baud_ID baud.menu BOUNDS \ insert as hierarchical menu 

* 300,600; 1200; 1890; 2400 ; 3608 ; 4800; 72009600; 19200” 
baud_menu ITEMS 


138 CONSTANT form_ID 

КЕМ МЕМ) form menu 

” Format” form.menu TITLE 

-1 form_ID form. menu BOUNDS \ insert as hierarchical menu 

* 5 data;6 data;7 data;8 data;(-; 1 stop;1.5 stop;2 stop” 
form_menu ITEMS 


131 CONSTANT parity_ID 

NEW.MENU parity.menu 

* Parity” parity menu TITLE 

-1 parity_ID parity_menu BOUNDS \ insert as hierarchical menu 
* попе; одд; even” perity menu ITEMS 


132 CONSTANT hsk_ID 

NEW.MENU hsk. menu 

* Handshake” hsk menu TITLE 

-1 hsk.ID hsk.menu BOUNDS \ insert as hierarchical menu 
“ none;xon-xoff;cts" hsk.menu ITEMS 


: do.conf ig 
baud? @ CASE 
1 OF $17C ENDOF 
2 OF $BD ENDOF 
З OF ФЕ ENDOF 
4 OF $3E ENDOF 
5 OF $2E ENDOF 
6 OF $1E ENDOF 
7 OF $16 ENDOF 
8 OF $E ENDOF 
9 OF $^  ENDOF 
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10 OF $4 — ENDOF 
ENDCASE 


data® @ CASE 
10F $6  ENDOF 
2 OF $800 ENDOF 
З OF $400 ENDOF 
4 OF $С00 ENDOF 

ENDCASE 

+ 


Stop? 6 CASE 
6 OF $4000 ENDOF 
7 OF $8000 ENDOF 
8 OF %С000 ENDOF 


ENDCASE 
+ 


раг11у8 6 CASE 
1 or $0 ENDOF 
2 OF $1009 ENDOF 
3 OF $3000 ENDOF 

ENDCASE 

+ 


hsk® @ CASE 
10F $0 ENDOF 
2 OF $10000 ENDOF 
3 OF $20000 ENDOF 

ENDCASE 

* 


commi MODE IF 10 call sysbeep THEN 


: init.menus 


7 


TermMenuBar ADD 

TermMenuBar Apple.menu ADD 
Apple.menu 6 *drvr CALL AddResMenu 
TermMenuBar term menu ADD 
TermMenuBar baud menu ADD 
TermMenuBar form menu ADD 
TermMenuBar parity. menu ADD 
TermMenuBar hsk.menu ADD 

baud.ID — term.ID 1 branch.menu 
form.ID — term.ID 2 branch.menu 
perity-ID term ID З branch.menu 
hsk.ID term. ID 4 branch.menu 
baud.menu 69-1 call checkitem 
form.menu 64-1 call checkitem 
form menu 68-І cell checkitem 
parity_menu 6 1 -1 call checkitem 
hsk. menu @ 1 -1 call checkitem 
9 baud? |! 

4 data® ! 8 stop! ! 

1 parity® ! 1 hsk® | 

do.conf ig 


: do.ebout 128 9 CALL alert drop ; 


: do.epple { item! ) 


V item! = 1 CAbout...)? 
item! 1 = 

IF do.about 

ELSE 


Apple.menu 6 item? DAName CALL GetItem 
DAName CALL OpenDeskAcc DROP 
THEN ; 


: do.baud 


baud. menu @ over -1 call checkitem 
baud.menu ё baud? 6 Ø call checkitem 
baud? ! 
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: do.format 

form menu @ over -1 call checkitem 

dup 5 « IF 
form.menu 6 data8 6 Ø call checkitem 
date? ! 

ELSE 
form.menu 6 stopt 6 Ø call checkitem 
Stop? ! 

THEN 


: do.parity 
perity.menu 6 over -1 call checkitem 
parity_menu ё parity 6 Ø call checkitem 
parity® ! 


: do.hshake 
hsk_menu 6 over -1 call checkitem 
hsk.menu 6 hsk® 6 Ø call checkitem 
hsk? ! 


: do.term 
CASE 
5 OF bye ENDOF 
ENOCASE 


: termmenuhandler (С ізет” menuID - ) 
CASE 
apple_ID OF do.epple ENDOF 
baud_ID OF do.baud  ENDOF 
form_ID OF do.format ENDOF 
parity_IDOF do.parity ENDOF 
hsk_ID OF do.hshake ENDOF 
term_ID OF do.term ENDOF 
ENDCASE 
do. config 
9 call hilitemenu 


( terminal emulator code from PAS starts here ) 


$04 CONSTANT LINE.FEED С ascii ‘linefeed’ ) 
$20 CONSTANT SP ( ascii ‘space’ ) 


VARIABLE inputbuffer 
64 VALLOT ( 68 bytes for holding modem input) 


: emib console ( n- ) С send a single character to the 
Screen ) 
CONSOLE OUTPUT 
EMIT ; 
: emit>moden (n - ) С send a single character to the modem 
port) 
COMM1 OUTPUT 
EMIT ; 
: 2comm1 ( -n ) С this word will determine if the Modem 
Port ) 
COMM1 INPUT 
( has received апу characters. The number returned ) 
?TERMINAL ; 
( will indicete the number of characters waiting. ) 


: @commi ( -n ) С this word will read one character from 


the ) 
COMM1 INPUT 
( modem port. If no characters are ready, this ) 
KEY ; С word will wait. The task will be put to sleep ) 
( and awaken when the ioCompletion routine is ) 
( executed upon receiving a character. ) 
( type?screen is an enhanced version of the normal TYPE 
routine. ) 
C this word will filter out linefeeds. А linefeed is printed 
on ) 
( the Macintosh as а square box. ) 
: type?screen ( address length ) 
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length 0 00 
address I + Ce 
$7F AND 
address I + C! 


С throw away 8th bit ) 


address I + C@ LINE FEED = 
С look for a Linefeed) 
IF 
sp address I + С! 
THEN 
LOOP 
CONSOLE OUTPUT 
address length TYPE ; С type out the modified string) 


( replace LF with SP) 


: monitor-modem ( | temp ) 
?comm1 ( how many characters аге ready ? ) 
?DUP ( Note: The maximum # of chars must be) 
( less then 64. This is the default size) 
C of the Serial Driver buffer. ) 
IF 


: goaway-handler bye ; 
: Popp €-) 


Term dup CALL showwindow CALL selectwindow ; 


: start-comm 


ACTIVATE 
( assign the following code to EMULATOR ) 
[е] termmenuhandler menu-vector ! 
(41 goaway-handler goaway-hook ! 
Popup 
termmenubar @ call setmenubar call drawmenubar 
CLS 
CONSOLE OUTPUT .^ Ready >” CR 
BEGIN 
CONSOLE INPUT 
? TERMINAL 
IF 
KEY emit?modem С send char to modem. ‘no local echo’ ) 
THEN 


monitor-modem (С watch the serial port) 


( has the user pressed a key ? ) 


AGAIN 
-) temp С save number of unread characters ) р 
COMM1 INPUT : MODEM 
inputbuffer temp EXPECT term ADD ( make the term window ) 
( receive characters from modem) term EMULATOR BUILD 
inputbuffer temp type?screen ( tie the term window to the EMULATOR task ) 
( send this string to screen) init.menus т 
THEN ; TermMenuBar emulator mbar?task Sl 
EMULATOR start-comm ; ( launch task ) EPS 
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Forth Forum 
Programming for MultiFinder 


Forth background processing 
under MultiFinder 


As of October, there is a new operating system for the 
Macintosh which comes pretty close to real multitasking. The 
MultiFinder, also known as Juggler, was introduced; many of 
you are probably familiar with its operation by now. 

This month we'll see how to interface Mach2 and MacForth 
applications to the MultiFinder so that they use as little memory 
as possible, are friendly to other applications running in the same 
environment, and keep doing their job while they're in the 
background. 


summary of FORTH multitasking 


Multitasking Forth systems like Mach2 or MacForth, even 
before the advent of Juggler, already had a mechanism built in 
that is very similar to what Juggler does. When a task has nothing 
to do for a while, at certain strategic points in the program it 
passes control back to the task scheduler, who then calls up the 
next task. 

This is not real multitasking since a task can be nasty and 
never let loose of the CPU once it has gained control, effectively 
stopping all other activity. In a real multitasking system, an 
interrupt-driven task scheduler would give control to the other 
processes anyway, avoiding such a dead-end situation. In a 
pseudo-multitasking environment such as Mach2 or MacForth, 
the task itself has the responsibility of not staying active for too 
long and letting the others have a turn. (The following examples, 
again, refer to Mach2. The same or similar Forth routines are 
provided in MacForth, so there should be no difficulty in trans- 
posing between the two.) 

Task scheduling in Mach? is done ina way largely transparent 
to the programmer. Words used for I/O routines such as KEY, 
?TERMINAL, EMIT, and others, will contain a PAUSE, 
which isa word that returns control to the task scheduler. The idea 
being, of course, that during I/O operations there will usually be 
spare time to do other things. For long calculations without I/O 
in between, one would have to provide additional PAUSEs 
inside time-consuming loops. 

What does PAUSE do exactly? I am not going to give you a 
disassembly of the task scheduler here (you could easily do that 
by yourself), but the task swapping is very simple and described 
in detail in the Mach2 manual. The registers used by the task are 
saved on the stack, and the next task entered or skipped depend- 
ing on whether its STATUS field contains the value WAKE or 
SLEEP. WAKE, in fact, is the 16-bit value of a TRAP#n 
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instruction, where the exception vector points to the task sched- 
uler routine, while SLEEP is simply the value of a JMP instruc- 
tion (with the address of the nex task directly following), so that 
we'll jump to the next task without doing anything. 

For tasks which are awake, the trap routine will then restore 
the registers and, if necessary, execute the vectored menu, 
control, or user data handling routines. After having done this, 
control will be given to the task, until PAUSE is called again. 

One default Mach2 task, which is present in any Mach2 
application, is the I/O task. It functions as the main event loop for 
the program and will distribute events to the tasks that they 
belong to (e.g. for a mouseclick it will determine which window 
it occurred in and call the event handling routines that belong to 
the task that owns the window). The source code of the I/O task 
is contained in the newest releases of Mach2 and therefore open 
to any modification, which is going to be helpful for the interfac- 
ing with MultiFinder that we're about to do. 


MultiFinder's multitasking strategy 


If you substitute GetNextEvent for PAUSE in the previous 
paragraph, you get a pretty good idea of what MultiFinder is 
doing. For Macintosh applications, the interface to the multi- 
tasking environment is this well-known trap, GetNextEvent. The 
Macintosh operating system follows a strategy very similar to 
that of the Forth multitasker: when GetNextEvent is called, it is 
assumed that the application has finished one (small) part of its 
work and is asking what to do next. If there are several null events 
in a row, MultiFinder assumes there is nothing more to do in the 
foreground and transfers control to a background application. 
This application then will be given a null event, and itis assumed 
that during such null events the program is doing some useful 
background activity. The background application will also re- 
ceive update events if the window arrangement has changed. 
GetNextEvent, of course, had to be patched to implementthe task 
switching strategy. 

Iam trying to outline it for you іп the following, although I do 
not have all the necessary information; the MultiFinder develop- 
ment package, APDA document #KMSMFD, gives only hints as 
to what is happening. Nevertheless, if you are thinking of 
developing programs that take full advantage of the MultiFinder, 
you should of course get this brochure, full of development 
guidelines. Another part of the following information came from 
posts on BIX and other bulletin boards. 

First, context switching from the foreground to any back- 
ground application, while the foreground stays idle, will involve 
saving the registers and program counter of the CPU. Further- 
more, applications might have accessed and changed low mem- 
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ory globals; so a copy of the Toolbox globals area is saved with 
each application, just like in Switcher. In addition, MultiFinder 
is intelligent enough to notice any trap patching that is going on 
when the application starts up for the first time (I suppose 
MultiFinder assumes that all this is taking place before the first 
call to GetNextEvent, or looks at the SetTrapAddress calls to see 
which changes are made). Those trap patches are also saved with 
the application, and changed appropriately on context switching. 
АП this necessary switching information is saved in PCBs 
(process control blocks), which are located in memory just under 
the applications and just above the free memory and the system 
heap. 

‘Context switching’ therefore means that the background 
application will have full control over the Macintosh, including 
any trap or low memory patches that have been made. The 
drawback is that there is quite a lot of switching overhead due to 
all the low memory stuff that has to be moved. (In the future, 
those problems will be taken care of by a memory management 
unit). 

Clicking on any window that belongs to a background appli- 
cation will move that window to the front, activate it and move 
the previous foreground task into the background (just like 
Mach? did all the time). In fact, together with the window that 
was clicked, all other windows associated with that same appli- 
cation are also moved in front of all the others. Such a set of 
windows that belong to one application is called a Layer. A new 
set of Toolbox routines, the Layer Manager, takes care of 
updating and maintaining the different window sets in a correct 
fashion. 

When a background application is moved into the fore- 
ground, not only contexts are switched between the new and the 
old foreground application: also, a sequence of events occurs that 
seems to be very similar to the way Switcher changed from one 
application to another. In order to ensure correct scrap handling, 
any internal scrap maintained by the application has to be moved 
into the clipboard in a format that other applications can under- 
stand. This procedure is called scrap coercion and can be done in 
two different ways. 

The recommended way is to implement Suspend/Resume 
events in the program. These events have an event code of 15 in 
the what field of the event record, with bit 0 set in the message 
field for Resume and cleared for Suspend events. When a 
Suspend event is received by the application, it should convert its 
internal scrap (i.e. the TE scrap) to the desk scrap, and on a 
Resume event take whatever is in the desk scrap and convert it to 
its internal format. 

Applications that don't understand Suspend/Resume events 
are forced to go through a more time-consuming process on 
switching: MultiFinder, like Switcher, simulates cutting/pasting 
to an imaginary desk accessory. Applications that support desk 
accessories have to do scrap coercion on that occasion, and the 
clipboard will be updated. 

A third activity that has to occur is that the new frontmost 
window has to be activated while the old front window gets 
deactivated. MultiFinder will automatically, together with the 
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Resume event, feed an activate event to the proper window when 
it is moved into the foreground, while the window going to the 
background receives a deactivate event. However, applications 
that fully support MultiFinder will not need these activate/ 
deactivate events since they can do the necessary activations and 
deactivations on the Resume and Suspend events. 


16-bit flag word: 
bi(s) use 


15 unused by MultiFinder 

14 0 = application does not understand 
suspend and resume events 
1 = application understands suspend and 

resume events 

13 unused by MultiFinder 

12 0 = application cannot do backgrounding 
1 = application supports backgrounding 


11 0 = application is not MultiFinder Aware 
1 = application is MultiFinder Aware 
0-10 unused by MultiFinder 
32 bit word: preferred memory size 


32 bit word: minimum memory size 


Table 1: The SIZE IDz-1 resource. 


To indicate the level of compatibility with the MultiFinder, 
the SIZE ID=-1 resource (table 1), known from Switcher, con- 
tains some new flags. Bit 14 of its 16-bit flag word indicates 
whether the application supports Suspend/Resume events (like 
under Switcher); bit 12 indicates whether the application should 
be periodically called and given a null event while the foreground 
task is idle; and bit 11 tells whether the necessary activation and 
decativation of the frontmost window are done automatically on 
Suspend/Resume events or whether additional activate/deacti- 
vate events have to be provided by MultiFinder. If your applica- 
tion is fully MultiFinder compatible, all of these bits should be 
set. 

The two long words following the flag word indicate the 
preferred and minimum memory size, as before under Switcher. 


Making Mach2 programs run in the background 


The most interesting thing about MultiFinder is that it allows 
most existing applications to continue running in the back- 
ground, if they are set up to perform activities while null events 
arereceived. Programs written in the Mach2 multitasking system 
are perfectly adapted to background processing, since the Forth 
multitasker keeps on going as long as each task calls PAUSE 
regularly. Events are taken care of by the I/O task and automati- 
cally distributed between the various other tasks. Null events will 
just transfer control from the I/O task to the next task in the list 
(see the main event loop at the end of listing 1; when a null event 
is received, the IOtask executes a PAUSE). Therefore, when a 
Mach2 application receives a null event, all its tasks will execute 
once in a row, until the IOtask gets control again and calls 
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GetNextEvent. This will happen no matter whether the Mach2 
program runs in the foreground or in the background. 

So, even if your Mach2 program does not support suspend 
and resume events and the automatic window activation and 
deactivation on switching, you can still have it run in the 
background. Simply setting the canBackground bit, bit 12 in the 
flag word of the SIZE resource, will keep the program running. 
To illustrate this, you should now load the Reflections example 
from the Mach2 demo disk (Listing 2), which draws nice line 
patterns in a small window. The main loop contains a PAUSE so 
that this program is polite and lets the other tasks have a turn. 
TURNKEY the program and then change its canBackground bit 
to 1, using ResEdit. Also, set the preferred memory size to 100K 
and the minimum size to 80K; this is largely sufficient, and the 
default given by the Mach2 system is much higher. You can keep 
a SIZE resource with these settings in the MACH.RSRC file so 
that it will automatically be added to any turnkey application. 

Isuppose your Macintosh is running Juggler at this moment, 
if not, you're out of luck. After you've turnkeyed and ResEdited 
the demo program, start it and you'll see the patterns moving in 
the window; then click on any Finder window to move it to the 
foreground. You'll notice that the lines continue to move in the 
background. 


WaitNextEvent and modification of the lOTask 


Satisfied? There is more we can do. The way our demo runs 
now, MultiFinder will waituntil two successive null events have 
been received through GetNextEvent and on the third one trans- 
fer control to a background task. As long as the foreground task 
stays idle, the background tasks will be called one after the other. 
However, the foreground application still receives control peri- 
odically, getting a null event. This is because a priori we don't 
know how long we may take control away from it, and it might 
have to do some ‘idling’ activities itself, such as blinking the 
caret. If the program had been properly designed to work with 
MultiFinder, we could have used a new trap that tells the system 
how long it may stay away before re-transferring control to the 
foreground application. This trap is called WaitNextEvent, and 
it is called as follows (Pascal syntax): 


function WaitNextEvent CeventMask: Integer; VAR theEvent: 
EventRecord; sleep: longint, mouseRgn: RgnHandle): BOOLEAN; 


Its trap code is $A860. The Forth interface to this trap is given 
in listing 1. 

WaitNextEvent called with sleep and mouseRgn equal to 0 
works just exactly like GetNextEvent. However, when sleep 
contains a nonzero value, that is supposed to be the number of 
ticks that the application may be 'put to sleep' by MultiFinder 
before being called again when there is no non-null event 
waiting. This means, if during idling you just want to blink the 
cursor twice a second, you may call WaitNextEvent with a sleep 
value of 30. When a non-null event like a key down or mouse 
click occurs, control will be transferred to the foreground routine 
immediately. 
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The mouseR gn region handle indicates a region inside which 
the cursor does not have to be changed upon mouse movement. 
When this handle is nonzero, any mouse movement outside the 
given region will generate a ‘mouse-moved’ event, which is an 
app4event (like Suspend and Resume) with event codez15 and 
$ЕА in the high byte of the event message. When mouseR gn is 
nil, no mouse-moved events will be generated. 

The call to GetNextEvent is made by the IOTask under 
Mach2. We can now modify the IOTask in such a way that 
WaitNextEvent will be used instead. Listing 1 gives the details. 

First, we have to verify that Juggler is running and the call to 
WaitNextEvent is a valid trap call. This can be done easily by 
comparing the trap address of WaitNextEvent to that of Un- 
knownTrap ($A89F), which is never implemented. If the two 
values are different, Juggler is installed. If they are the same, 
we'll have to call good old GetNextEvent. 

Of course, this comparison won't be done on every GetNex- 
tEvent call. We should seta flag at the beginning of our program 
that indicates the state of the system. The initialization code of a 
Mach2 application, however, is not readily accessible, so we 
catch the first call to the Forth word GetNextEvent and deter- 
mine at that point whether we can WaitNextEvent or not. We then 
set a flag accordingly, which will be checked on every following 
GetNextEvent call. If we call WaitNextEvent, we won't have to 
call SystemTask periodically, either; its function is taken over by 
WaitNextEvent. 

With this modification the IOTask will take care of returning 
control to other background applications when null events are 
occurring. You might now think that one should put a value of 
some 3 to 30 ticks into the sleep parameter, since we don't need 
to come back so often when nothing special is happening. This is 
not so; according to my experimentation, the maximum sensible 
value for sleep in the IOTask event loop is 1 (one). The reason for 
this is the way events are dispatched by the Forth system. The 
IOTask takes all pending events and calls the event handling 
routines of the frontmost Forth task during one turn of its 
execution. It only transfers control to the next Forth task when no 
more events are pending, i.e. the event returned is a null event. At 
this point, however, MultiFinder will give control to a back- 
ground application and only return after sleep ticks have expired. 
Since the event queue has just been emptied, it is very likely that 
this time really elapses before control is returned to the fore- 
ground task with a null event and the Forth tasks can have around 
of execution. Again, this round will stop at IOTask, wait for sleep 
ticks, and so on. 

In practice this means that setting sleep to a value greater than 
1 (maybe 2) will slow down the Mach2 system in an unacceptable 
manner. For instance, keystrokes are processed by the individual 
Forth tasks, not by the IOTask, which only puts them into the 
tasks' keyboard buffers. If you set sleep to 30 ticks, you will then 
be typing ata rate of less than two letters a second. Although I am 
a slow typist, this slows me down too much... 

Let this just be a warning to be careful with the sleep 
parameter; it might of course be set to higher values depending 
on what one wants the Forth application to do. For programs that 
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run *background-only', we might afford much longer naps. 

If you modify the IOTask in the way indicated in listing 1, the 
Mach2 system won't be slowed down too much and background 
activity will run a little more smoothly. You might also define a 
sleep parameter that can be changed while the tasks are running, 
by storing it in a variable close to the event table. That way it can 
be accessed from within the Mach2 program through an offset 
from EVENT-TABLE. 

I have not yet changed the IOTask in a way to support 
Suspend/Resume events. This is pretty straightforward: one 
would have to define a vector in the user variable table where a 
vector to the Suspend/Resume handler is kept, and let the IOTask 
call it when the event is received. The IOTask would also 
deactivate, resp. activate the frontmost window by calling the 
activate handler. 

Talking about sleep parameters for such a long time almost 
makes me fall asleep, so I'll let you go for this month. 

Happy Threading. 


Listing 1: MultiFinder support for Mach2 

V € 1987 J.Langowski / MacTutor 

\ with parts of the code 9 Palo Alto Shipping 

\ add this code to the IOTASK code supplied by 

\ Palo Alto Shipping, and modify main event loop as indicated 


.TRAP _WaitNextEvent $4860 


CODE WaitNextEvent 

C eventMask VAR-eventRecord sleep mouseRgn - flag ) 
EXG D4,A7 
CLR.W -САТ) V function result 
MOVE.W $ECA6),-CA7) \ eventMask 
MOVE.L $8(A6),-CA7) \ eventRecord 
MOVE.L $4САб ),-САТ) \ sleep 
MOVE.L САб),-САТ) V mouseRgn 
ADDA .W #$ 10, A6 
-WaitNextEvent 
MOVE.W САТ )+,00 \ flag -> 00 
EXT.L 00 \ extend sign 
MOVE.L 00,-СА6) \ push on Forth stack 
EXGD4,A7 
RTS 

END-CODE 


Header JugglerThere -1 , 
\ initially -1 so that first call 
\ to GetNextEvent will determine state 


\ zzzzzzzzz The Main Loop zzzzzzzzzzz 


: DialogEvent? С - f 2 

\ If event is dialog event which should be handled 

\ by our application 

\ Cusually be being passed to DialogSelect), 

\ IsDialogEvent will return a true flag. If event 

\ should be handled as а normal, non-dialog event, \ false 
will be returned. 

EVENT-RECORD CALL IsDialogEvent ; 


: GetNextEvent С -f 2 
\ If an event occurs which should be handled, 
\ GetNextEvent will return a true flag. 
\ The event code and any other event information 
\ will be returned in the EVENT-RECORD. 
X changed for Juggler support 26.8.87 JL 
[^] JugglerThere 8 CASE 
1 OF \ Yes, we can juggle 
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EveryEvent Event-Record 1 0 WaitNextEvent 
ENDOF 

0 OF  \ го, we can't 
CALL SystemTask 

\ built in here since WaitNextEvent doesn’t need it 
EveryEvent Event-Record CALL GetNextEvent 
ENDOF 

-1 OF WNETrap® CALL GetTrapAddress 

UnkTrap® CALL GetTrapAddress 

= IF CALL SystemTask 0 
ELSE 1 THEN 
[‘] JugglerThere ! 
EveryEvent EVENT-RECORD CALL GetNextEvent 
ENDOF 

0 \ we should never get here 

ENDCASE 


\ zzzzz (IOTASK) ===== 
: (10Task) ( | dialogflag eventflag - ) 
BEGIN 
BEGIN 
Ge tNextEvent -> eventf lag 
DialogEvent? -) dialogflag 


dialogflag IF 
HandleDialog 
ELSE 
eventflag IF HandleEvent THEN 
THEN 
eventf lag 0- 
UNTIL 
PAUSE 
AGAIN ; 


Listing 2: Reflections demo from Mach2 


\ Reflections 

X Mach2. 12 Demo 

X 6/87 

V Palo Alto Shipping Company 


\ Description: 

V (xx d,yyl) and (xx2,yy2) are two points that travel 

\ around the reflections window. Their speeds are 

\ the delta values held in the DOT variables. When a 

\ point runs into a wall, it’s x or y speed is negated 
\ so that it bounces off the wall. All the while a line 
V is drawn between the two points and the line drawn 20 
\ steps ago is erased. 


ONLY FORTH DEFINITIONS ALSO MAC 
DECIMAL 


\ QuickDraw Equates 
$8 CONSTANT PatCopy 
$B CONSTANT PatBic 
$10 CONSTANT PortRect 


\ Window Size Variables 
VARIABLE WTop 

VARIABLE WLeft 
VARIABLE WBottom 
VARIABLE WRight 
VARIABLE  WWidth 
VARIABLE WHeight 


\ Positions \ Velocities 

VARIABLE xx1 VARIABLE xx1DOT 
VARIABLE yy] VARIABLE yy 100Т 
VARIABLE xx2 VARIABLE xx2DOT 
VARIABLE yy2 VARIABLE yy2D0T 


\ Menu constants and variables. 
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VARIABLE DeskName 252 VALLOT 
$44525652 CONSTANT ‘DRVR’ 


CREATE AppleString 

V Creating title string for AppleMenu. 
$91 C, \ Length byte. 

$14 C, \ Apple character. 


\ Creating a window named ‘Reflections’. 

NEW.WINDOW Reflections 

* Reflections” Reflections TITLE 

8115 8315 8265 8465 Reflections BOUNDS 

ROUNDED VISIBLE NOCLOSEBOX NOGROWBOX 
Reflections ITEMS 


V ‘LinesTask’ is а task w/ 800 bytes of param stack. 


8800 81000 TERMINAL LinesTask 


\ Give ‘Reflections’ а menubar. 
NEW.MBAR Ref lectMBar 


NEW . MENU AppleMenu 

AppleString AppleMenu TITLE 
Q #998 AppleMenu BOUNDS 
* (Reflections; (-^ Арр1еМепи ITEMS 


NEW.MENU FileMenu 

* File” FileMenu TITLE 
Q 8999 FileMenu BOUNDS 
* Quit/Q^ FileMenu ITEMS 


: HandleDeskAcc ( item! | saveport - ) 
^ saveport CALL GetPort 
AppleMenu 8 item? DeskName CALL GetItem 
DeskName CALL OpenDeskAcc DROP 
saveport CALL SetPort ; 


: DoApple С item? - ) HandleDeskAcc ; 


: DoFile € item? - DROP BYE ; 


: MbarHandler С item? menuID - ) 
CASE 
#908 OF DoApple ENDOF 
#999 OF DoFile ENDOF 
ENDCASE 
@ CALL HiliteMenu ; 


: RANGE ( value hi 1o - value flag ) 
value hi value > 10 value < OR NOT ; 


: 4DUP Cni n2 n3 n4 - n1 n2 n3 n4 n1 n2 n3 n4 D 
83 pick #3 pick 83 pick 83 pick ; 


: GetWCoords ( wptr | wrect - ) 
wptr PortRect + -> wrect 
wrect мё | ЕХТ WTop | 
wrect 2% We | EXT WLeft ! 
wrect 4 + We L EXT WBottom ! 
wrect 6 * We L_EXT WRight ! 


WBottom @ WTop ё - WHeight ! 
WRight ё WLeft 8 - — WWidth ! 
: Exit? C- f ) 


?TERMINAL IF 
KEY IF BYE THEN 
THEN ; 


: SetupReflect С - ) 
Reflections CALL SetPort 
CLS 
Width e 3 / xx1! 83 xxIDOT |! 
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WHeight @ yyl ! 8-4 yy1DOT ! 
Width@ 3 /2* xx2 ! 4 xx2D0T ! 
WHeight @ yy2 ! 8-3 yy2D0T ! ; 


\ Draws а newline and leaves, coords on stack. 
: NewCoords С - xxi yy! xx2 yy2 ) 

хх 1004 ё xx1 +! yylDot @ yy! +! 

xx2Dot @ xx2 +! yy2Dot ё yy2 +! 


xx1 ё 1 WWidth ё RANGE NOT 
IF xx1Dot ё NEGATE xx1Dot ! 
THEN 


yy1 ё 1 WHeight ё RANGE NOT 
IF gy1Dot @ NEGATE yylDot ! 
THEN 


xx2 @ 1 WWidth @ RANGE NOT 
IF xx2Dot @ NEGATE xx2Dot ! 
THEN 


yy2 @ 1 WHeight @ RANGE NOT 
IF yy2Dot @ NEGATE yy2Dot ! 
THEN ; 


\ Leaves 48 coordinate pairs on the stack and draws the 


V ist 20 lines. 
: First20Lines С - ) 


820 0 DO 
Ref lectionsCALL SetPort 
PatCopy CALL PenMode 


NewCoords 4DUP 
CALL MoveToCALL LineTo 


LOOP ; 
: LinesForever С - ) 
BEGIN 
ReflectionsCALL SetPort 
PatCopy CALL PenMode 


NewCoords 4DUP 
CALL MoveTo 


CALL LineTo ( 21 complete sets on =) 84 values) 


#83 ROLL #83 ROLL #83 ROLL #83 ROLL 


PatBic CALL PenMode С and white out the n-21st line) 


CALL MoveToCALL LineTo 
exit? AGAIN ; 


: Reflect € - > SetUpReflect First20Lines LinesForever ; 


: InitMBer (С - ) 
ReflectMBar ADD 
Ref lectMBar AppleMenu ADD 
Ref lectMBar FileMenu ADD 
AppleMenu @ 'DRVR^ CALL ADDRESMENU 
Ref lectMBar @ CALL SetMenuBar 
CALL DrawMenuBer ; 


: InitStructures С - ) 
Reflections ADD 
Reflections CALL SelectWindow 
Reflections GetWCoords 
Ref lections LinesTask BUILD 
InitMBer ; 


: Run € taskptr - ) 
ACTIVATE 
[^] MbarHandler MENU-VECTOR ! 
Ref lectMBar LinesTask MBAR» TASK 
Reflect ; 


: BootLines С - )  InitStructures LinesTask Run 
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Extending Hypercard from Forth НуреғСаға 


Hypercard external functions and commands 

One of the major events in the last couple of months on the 
Macintosh scene has been the introduction of Hypercard (You've 
read an article on it in the last MacTutor). This month's column 
will deal with interfacing Forth code to Hypercard; we shall see 
how an external command can be implemented in Mach2. 

The syntax of Hypertalk commands 

A ‘command’ in the Hypertalk language is a word followed 

by a number of parameters, separated by spaces. Example: 


dial it with modem 


will execute the dial command and pass the parameter string: "it 
with modem" . Dial will then know how to deal with that string; 
in this case, get the ASCII string stored in it, interpret itas a phone 
number to be dialed and issue the appropriate Hayes-compatible 
modem command. 

Similarly, if we define our own command, munch, we may 
send parameters to it, “three bars of milk chocolate" , and the 
corresponding Hypertalk line will read: 


munch three bars of milk chocolate 


The concept, as you see, is very simple. All we now need to 
know 1s how such an external command is implemented, i.e., how 
the Hypertalk system finds the command and how the parameters 
are passed. 

How an external command is found 

Anexternal command is stored as aresource of type XCMD. 
The resource name is the name of the external command as called 
through Hypertalk. I have not peeked inside Hypertalk's guts yet, 
but it seems to me very probable that a GetNamedResource is 
used to get an XCMD that is to be executed. 

The resource is a piece of executable 68000 code, just like a 
WDEF or MDEF would be. When the XCMD is executed, the 
system jumps to the beginning of the resource. There, on top of 
the stack a pointer to a parameter block is passed, which looks 
like the following (in Pascal notation): 


XCmdPtr = “XCmdBlock; 

XCmdBlock = RECORD 
paramCount: INTEGER; ( the number of arguments ) 
params :ARRAY[1..16] OF Handle; ( the arguments ) 
returnValue: Handle; ( the result of this XCMD } 
passFlag: BOOLEAN; ( pass the message on? } 


entryPoint: РгосРіг; 
request: INTEGER; (һай you want to do ) 
result: INTEGER; ( the answer it gives ) 
inArgs: ARRAY[1..8] OF LongInt; 

{ args XCMD sends HyperCard } 


{ call back to HyperCard } 
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outArgs: ARRAY[1..4] OF LongInt; 
( answer HyperCard sends back ) 
END; 


А Hypertalk function, in contrast to a command, will always 
return a value and its syntax is different from that of a command. 
For example: 


the exp of number 


will return the exponential of number. A Hypertalk line like 
that has no meaning, so we'll write, for instance: 


put the exp of number into it 
and it will contain the result. An alternative syntax would be 
put exp(number) into it. 


An external function is stored as a resource of type XFCN, 
with the resource name being the name of the function, like for 
the XCMDs; again, it is called by jumping to the start of the 
resource. 

The parsing of the line following the command or function 
is automatically done by Hypercard; the arguments (i.e., the 
words following the command) are passed to the XCMD in form 
of handles to zero-terminated strings. The XCMD that we write 
can do whatever necessary with them. If you want, you may 
return a result by storing a handle to it in returnValue. (All data 
values going to and from HyperTalk are zero-terminated ASCII 
strings). A result that has been stored in this field can be accessed 
by the user in the variable 'the result' after executing a com- 
mand. In a function, returnValue is always expected to contain 
something. 

passFlag is used to determine whether the command has 
been executed successfully. If this flag is false, the XCMD or 
XFCN has handled the message and the script resumes execu- 
tion. If passFlag is true, HyperCard searches the remaining 
inheritance chain for another handler or XCMD with the same 
name. This is just like the ‘pass’ control structure in a script. 

You may also call HyperCard from within your code. This 
is what the second part of the parameter block is used for. To call 
HyperCard commands, you put your arguments into inArgs, the 
command code into request, and call the routine pointed to by 
entryPoint. HyperCard returns the values you requested in 
outArgs and a result code in result. 

The command and result codes are part of a Pascal definition 
in the Hypercard developer package materials. They are given in 
Listing 1, together with a description of what the commands do. 
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Mach2 implementation 
The example program (Listing 1) will create an XCMD that 
inverts the screen a given number of times, like the built-in flash 
command. The difference is that the result will return Done 
when the command was executed successfully and Error when 
a negative number has been given as a parameter (incorrect). Its 
syntax will be: 


flashy «number? 


where «numbers» is a string that is interpreted as a decimal 
number. 

Now look at the example. You'll recognize the glue code 
that is used in the XCMD definition to setup the Forth stack and 
transfer the parameters from the Pascal to the Forth stack; I 
defined in the form of a MACH macro so the definition of the 
actual glue routine becomes very simple. The XCMD is embed- 
ded between the labels flashy.start and flashy.end. callJSR is 
aredefinition of the kernel word execute, which does a JSR to an 
address given on the stack. This word is needed in the two 
following words, ZeroToPas and StrToNum, which call 
Hypercard routines through the entryPoint parameter in the 
Hypercard parameter block. ZeroToPas converts a C string 
(zero-terminated) to a Pascal string (count byte followed by 
characters). StrToNum takes a Pascal string and interprets it as 
a number. Both routines also need to be given the address of the 
Hypercard parameter block containing Hypercard's entry point. 

For the other Hypercard functions that may be called from 
outside, see theirrequest codes and Pascal definitions given at the 
beginning of the listing. With the two routines given here as an 
example, you can easily figure out how to call the remaining 
ones. I also strongly recommend reading the documentation and 
Pascal or C example files that come with the Hypercard 
developer's package, which you may obtain through APDA 
(DDA in France, see below). 

The actual XCMD, flashy, first gets the first parameter, 
which is a handle to astring, then converts this string to a number. 
If the number is negative, it will return “Error” as a return string, 
if it is positive, it flashes the screen for this number of times and 
returns "Done". 

The last part of the listing will simply create a file containing 
the new resource. 

Calling the XCMD from Hypercard 

When you've created the file “xcmd.res”, enter ResEdit and 
install the XCMD resource in your home stack (or any other 
stack, for that matter). Then you can call Hypercard and, for 
example, create a button which has the following script: 


on mouseup 

flashy 10 

put the result 
end mouseup 


Pushing this button, then, should flash the screen ten times 
and display “Done” in the message window. If you change the 
number to -10, no flashing should happen and “Error” should be 
displayed in the message box. 

You may try to change the resource type to XFCN; this will 
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change the syntax to (for example) 


on mouseup 
put flashyC10) 
end mouseup 


but should not otherwise affect the behavior of the com- 
mand. 
Feedback Dept. 
Mac Applications In Forth? 
Paul Thomas 
Danville, CA 

Q. Can Forth be used on the Mac to do software stuff: i.e. 
games, engineering applications, etc.? I just picked up “Mach?” 
last month and I’ve been reading Leo Brodie's “Starting Forth". 
I was studying the Mac Toolbox using Turbo Pascal, but I went 
over to Palo Alto Shipping and visited with Rick Miley. I'm an 
engineering student (mechanical engineering) and he got me 
excited about Forth. Most of your articles tend to deal with 
hardware, data transfer, low level stuff. realize that Forth is great 
for that type of work, but I'd like to program the Mac in Forth. I 
haven't been able to find very many example programs in Forth. 
I guess I could try my hand at translating from Pascal and C to 
Forth. It's going to be tough though since I'm new at Forth - and 
it really IS different from Pascal or C. Are most of your readers 
interested in low level Forth work? Do you know of anyone who 
is programming applications in Forth? Most people that I know 
that program the Mac work in Pascal or C. 

Ido enjoy your articles (Thanks! JL]. I'd love to send you a 
message over CalvaCom, but it's a bit too expensive for me. I 
can't even afford Compuserve. Do you have an address on 
GEnie? 

А. Can Forth be used to do software stuff: why, yes! don't 
we do software stuff? In fact, I see what you mean and can only 
say that one full-fledged application in each column would 
probably be too much. If you've seen the space taken up by long 
articles in MacTutor, you'll understand that we cannot print a 
regular column that long each time. I might, however, think of 
working out a longer project and distribute that over several 
columns. The columns that I write, of course, also reflect to some 
extent how I use the Mac for my other work. Let me take this 
opportunity to repeat once again: This magazine lives through 
YOUR contributions, and nothing would I appreciate more than 
article submissions for the Forth column. 

Most people I know program the Mac in Pascal or C, too. 
Should I say unfortunately? The two Forth systems that I use, 
Mach2 and MacForth, are by far the fastest development systems 
that I know of. Having to write this month's example in Pascal 
without the glue routines available would have been a nightmare. 
With Mach2, the whole cycle of changing a line, recompiling, 
rewriting the resource file, calling ResEdit, installing the re- 
source, calling Hypercard and testing the XCMD takes about one 
minute. If Ihadn'tbeen that lazy, I'd have written a small routine 
that installs the XCMD in my Home stack directly, gaining 
another 30 seconds. 

[I can be reached on GEnie now. Mail address: 
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J.Langowski. I wish you all happy holidays, and happy thread- 
ing.] 


Listing 1: А screen invert Hypercard external command 
in Mach2 


( *** Hypercard external commands. J.L. October 1987 *** ) 
ONLY FORTH ALSO ASSEMBLER ALSO MAC 


4ascii XFCN CONSTANT "xfcn 
4escii XCMD CONSTANT “хста 


$9DE CONSTANT WMgrPort 
V structure of а Hypercard parameter block 


0 CONSTANT paramCount \ INTEGER; the number of arguments 
2 CONSTANT params X ARRAY([1..16)] OF Handle; the arguments 
66 CONSTANT returnValue \ Handle; the result of this XCMD 
10 CONSTANT passFlag А BOOLEAN; pass the message on? 

72 CONSTANT entryPoint \ ProcPtr; call back to HyperCard 

76 CONSTANT request \ INTEGER; what you want to do 

78 CONSTANT result \ INTEGER; the answer it gives 

80 CONSTANT inArgs \ ARRAYL1..8] OF LongInt; 

\ args XCMD sends HyperCard 

\ ARRAY(1..4] ОР LongInt; 

\ answer HyperCard sends back 


112 CONSTANT outArgs 


\ result codes 

0 CONSTANT xresSucc 

1 CONSTANT xresFail 

2 CONSTANT xresNotImp 


V request codes 

1 CONSTANT xreqSendCardMessage 
2 CONSTANT xreqEvalExpr 

З CONSTANT xreqStringLength 

4 CONSTANT xreqStringMatch 

5 CONSTANT xreqSendHCMessage 
6 CONSTANT xreqZeroBytes 

7 CONSTANT xreqPasToZero 

8 CONSTANT xreqZeroToPas 

9 CONSTANT xreqStrToLong 

10 CONSTANT xreqStrToNum 

11 CONSTANT xreqStrToBool 

12 CONSTANT xreqStrToExt 

13 CONSTANT xreqLongToStr 

14 CONSTANT xreqNumToStr 

15 CONSTANT xreqNumToHex 

16 CONSTANT xreqBoolToStr 

17 CONSTANT xreqExtToStr 

18 CONSTANT xreqGetGlobal 

19 CONSTANT xreqSetGlobal 

20 CONSTANT xreqGetF ieldByName 
21 CONSTANT xreqGetF ieldByNum 
22 CONSTANT xreqGetF ieldByID 
23 CONSTANT xreqSetF ieldBuName 
24 CONSTANT xreqSetF ieldByNum 
25 CONSTANT xreqSetF ieldByID 
26 CONSTANT xreqStringEqua! 

27 CONSTANT xreqReturnToPas 

28 CONSTANT xreqScanToReturn 
39 CONSTANT xreqScanToZero X was supposed to be 29. Oops! 


( **** Pascal definitions for the Hypercard routines follow: 
PROCEDURE SendCardMessage(msg: Str255); 

( Send a HyperCard message (a command with arguments) to the 
current card. } 

FUNCTION EvalExprCexpr: Str255): Handle; 

( Evaluate a HyperCard expression and return the answer. The 
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answer is a handle to a zero-terminated string. } 


FUNCTION StringLength(strPtr: Ptr): LongInt; 

( Count the characters from where strPtr points until the 
next zero byte. Does not count the zero itself. strPtr must 
be а zero-terminated string. ) 


FUNCTION StringMatch(pattern: Str255; target: Ptr): Ptr; 
( Perform case-insensitive match looking for pattern anywhere 
in target, returning а pointer to first character of the first 
match, in target or NIL if no match found. pattern is a 
Pascal string, and target is a zero-terminated string. } 


PROCEDURE ZeroBytesCdstPtr: Ptr; longCount: LongInt); 
( Write zeros into memory starting at destPtr and going for 
longCount number of bytes. ) 


FUNCTION PasToZero(str: Str255): Handle; 

( Convert а Pascal string to а zero-terminated string. 
Returns a handle to а new zero-terminated string. The caller 
must dispose the handle. You/l] need to do this for any result 
or argument you send from your XCMD to HyperTalk. ) 


PROCEDURE ZeroToPas(zeroStr: Ptr; VAR pasStr: Str255); 

( Fill the Pascal string with the contents of the zero- 
terminated string. You create the Pascal string and pass it 
in es а VAR parameter. Useful for converting the arguments of 
any XCMD to Pascal strings.) 


FUNCTION StrToLong(str: Str31): LongInt; 
( Convert a string of ASCII decimal digits to an unsigned 
long integer. ) 


FUNCTION StrToNumCstr: Str31): LongInt; 
( Convert a string of ASCII decimal digits to a signed long 
integer. Negative sign is allowed. ) 


FUNCTION StrToBool(str: Str31): BOOLEAN; 
( Convert the Pascal strings ‘true’ and ‘false’ to booleans. ) 


FUNCTION StrToExt(str: Str31): Extended; 
( Convert а string of ASCII decimal digits to en extended 
long integer. ) 


FUNCTION LongToStrCposNum: LongInt): Str31; 
( Convert ап unsigned long integer to a Pascal string. ) 


FUNCTION NumToStr(num: LongInt): Str31; 
( Convert a signed long integer to a Pascal string. ) 


FUNCTION NumToHexCnum: LongInt; nDigits: INTEGER): Str31; 
( Convert an unsigned long integer to a hexadecimal number 
and put it into a Pascal string. 


FUNCTION BoolToStr(bool: BOOLEAN): Str31; 

( Convert a boolean to ‘true’ or ‘false’. ) 

FUNCTION ExtToStr(num: Extended): Str31; 

( Convert an extended long integer to decimal digits in a 
string.) 


FUNCTION GetGlobalCglobName: Str255): Handle; 
( Return a handle to a zero-terminated string containing the 
value of the specified HyperTalk global variable. ) 


PROCEDURE SetGlobalCglobName: Str255; globValue: Handle); 

( Set the value of the specified HyperTalk global variable to 
be the zero-terminated string in globValue. The contents of 
the has ere copied, so you must still dispose it after- 
wards. 


FUNCTION GetFieldByNameCcardF ieldFlag: BOOLEAN; fieldName: 
Str255): Handle; 

( Return а handle to а zero-terminated string containing the 
value of field fieldName on the current card. You must dispose 
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the handle. ) 


FUNCTION GetF ieldBgNumCcardF ieldF lag: BOOLEAN; fieldNum: 
INTEGER): Handle; 

( Return а handle to а zero-terminated string containing the 
value of field fieldNum on the current card. You must dispose 
the handle. ) 


FUNCTION GetF ieldByIDCcardF ieldFlag: BOOLEAN; fieldID: 
INTEGER): Handle; 

( Return а handle to a zero-terminated string containing the 
value of the field whose ID is fieldID. You must dispose the 
handle. 


PROCEDURE SetFieldBygNameCcardF ieldFlag: BOOLEAN; fieldName: 
5іг255; fieldVal: Handle); 

( Set the value of field fieldName to be the zero-terminated 
string in fieldVal. The contents of the Handle are copied, so 
you must still dispose it afterwards. ) 


PROCEDURE SetFieldByNum(cardFieldFlag: BOOLEAN; fieldNum: 
INTEGER; fieldVal: Handle); 

( Set the value of field f ieldNum to be the zero-terminated 
string in fieldVal. The contents of the Handle are copied, so 
you must still dispose it afterwards. ) 


PROCEDURE SetFieldByID(cardF ieldFlag: BOOLEAN; fieldID: 
INTEGER; fieldVal: Handle); 

( Set the value of the field whose ID is fieldID to be the 
zero-terminated string in fieldVal. The contents of the 
Handle are copied, so you must still dispose it afterwards. ) 


FUNCTION StringEqual(stri,str2: Str255): BOOLEAN; 
( Return true if the two strings have the same characters. 
Case insensitive compare of the strings. ) 


PROCEDURE ReturnToPas(zeroStr: Ptr; VAR pasStr: Str255); 

( zeroStr points into a zero-terminated string. Collect the 
characters from there to the next carriage Return and return 
them in the Pascal string pasStr. If a Return is not found, 
collect chers until the end of the string. ) 


PROCEDURE ScanToReturn(VAR scanPtr: Ptr); 
( Move the pointer scanPtr along a zero-terminated string 
until it points at a Return character or a zero byte. ) 


PROCEDURE ScanToZero(VAR scanPtr: Ptr); 
( Move the pointer scanPtr along a zero-terminated string 
until it points et a zero byte. ) 


**** End of Pascal definitions ) 
| **** Hypercard glue macros 


CODE HC.prelude 
LINK Аб, 8-5 12 ( 512 bytes of local Forth stack ) 
MOVEM.L A®-A5/D@-D7,-CA7) С save registers ) 
MOVE.L A6,A3 С setup local loop return stack ) 
SUBA.L #256, АЗ ( in the low 256 local stack bytes ) 
MOVE.L 8СА62,00 С pointer to parameter block ) 
MOVE.L 00,-САб) 
RTS \ just to indicate the MACHro stops here 
END-CODE MACH 


CODE HC .epi logue 
MOVEM.L (А72%,А0-А9/00-07 С restore registers ) 
UNLK A6 


MOVE.L (CA7)+,A®8 C return address ) 


ADD .W 84 AT С pop off 4 bytes of parameters ) 
JMP (AQ) 
RTS 


END-CODE MACH 
CS) 
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header flashy.start 
JMP fleshy.start С to be filled later ) 


heeder doneString 
DC.B ‘Done’ 
DC.B 0 


header errorString 
DC.B ‘Error’ 
DC.B 0 


header PascalString 255 allot 


CODE callJSR 
MOVE.L CA6)+,-CA7) 
RTS 
END-CODE 
: ТегоТоРав  ( HCPars CStr PStr | - } 
CStr HCPars inArgs + ! 
PStr HCPars inArgs + 4 +! 
хгедѓегоТоРаѕ HCPars request + w! 
HCPars entryPoint + @ callJSR C call Hypercard here ); 


: StrToNum ( HCPars Str | - result ) 
Str HCPars inArgs + ! 
xreqstrToNum HCPars request + w! 
HCPars entryPoint + @ callJSR 
HCPars outArgs + ё; 


: flashy ( HCpars | hP1 screen times - ) 
HCPers params + ё -> hP1 \ handle to first parameter 
V (zero-terminated string) 
hP1 (са11) HLock drop V yes, I know I’m paranoid 
HCPars hP1 6 171 PascalStr ing 
ZeroToPas 
hP1 (call) HUnLock drop 
HCPars ['] PascalString 
StrToNum -> times 
times Ø IF 
WMgrPort 6 -> screen 
times 0 DO 
screen portRect + dup 
(call) InvertRect (call) InvertRect 
LOOP 
[^] doneString 5 (call) PtrToHand drop 
HCpars returnValue + ! 
ELSE € if it is negative, return an error ) 
[*] errorString 6 (call) PtrToHand drop 
HCpars returnValue * ! 
THEN; 
: flashy.glue 
HC.prelude flashy HC.epilogue ; 
header f'lashy.end 
( now setup correct entry address ) 
* flashy.glue ' flashy.start 2+ - ' flashy.start 2+ w! 


С *** making the XCMD resource *** ) 
: $create-res call CreateResFile call ResError L_ext ; 


: $open-res ( addr | refNum - result ) 
addr call openresfile -» refNum 
call ResError L.ext 
dup not IF drop refNum THEN ; 
: $close-res call CloseResFile call ResError L_ext ; 


: make-xcmd ( | refNum - ) 
" xcmd.res^ dup $create-res 
abort” You have to delete the old ‘xcmd.res’ file first.” 
$open-res dup -> refNum call UseResFile 
(*] fleshy.start [°] flashy.end over - 
call PtrToHand drop С result code ) 
“xcmd 2000 " flashy” call AddResource 


refNum $close-res drop ( result code ); 
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Fortran's World 


Controls from Fortran 


Previous articles and examples in MacTutor have shown 
how to incorporate features of the Macintosh user interface such 
as menus and windows into FORTRAN applications. This 
article will show how to implement simple controls such as 
buttons, checkboxes and radio buttons. 

The text will identify which tool box routines to call, where 
to call them and why. The example is a modified version of the 
shell program дето, ог supplied by MicroSoft. It will give the 
details of how to implement controls in FORTRAN. 

Control Basics 

The three types of standard controls: buttons, checkboxes 
and radio buttons are on/off switches and have control definition 
ID's of 0, 1 and 2. The scrollbar is a type of control known as a 
dial since it can take on more than two values. It has a control 
definition ID of 16. These ID's specify to the control manager 
what type of control to create. 

A control is either active or inactive, i.e. highlighted or 
unhighlighted. A control can also be visible or invisible. Only 
when a control is active and visible will it respond to the mouse. 

А control has another attribute known as a part number. 
Each part of a control has a unique part number. Simple controls 
such as buttons, check boxes and radio buttons have only one part 
and hence only one part number. The scroll bar on the other hand 
is more complicated and has five parts: elevator box or thumb, up 
arrow, down arrow, up button and down button. Part numbers 
and control definition ID's for the standard controls are listed in 
Figure 1. 


tion ID 


push button 
check box 
radio button 
scroll bar 


inUpButton 
inDownButton 
inPageUp 
inPageDown 
inThumb 


Records Needed to Implement Controls 
Control Record, A record is a Pascal data type used on the 
Macintosh to describe or specify windows, dialogs, controls, 
events, etc. Each control that is defined has a control record 
associated with it. A control record consists of 13 fields. Figure 
2 lists these fields and gives decimal offsets which can be used to 
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Our Control Example with two windows! 
access the individual fields of the control record from FOR- 
TRAN. For example if CONTROLBEG is an INTEGER*4 
variable containing the beginning address of the control record 
then the FORTRAN statement LONG(CONTROLBEG44) will 
givethecontrlOwner field of the control record. This field points 
to the window that contains the given control. Most of the fields 
in the control record can be accessed through tool box calls rather 
than directly with the LONG function. An exception is the first 
field of the control record, named nextControl, which is a handle 
to the next control in the window's control list. The fields of a 
control record that we will use to implement controls are: 
nextControl, controlValue and contrIRfcon. 

The parameter, nextControl, is a handle for the next control 
record in the window's control list. So the control record for the 
next control in a window starts at the address given by the 
FORTRAN statement: 

LONG(LONG(nextControl)) 

When handling activate events one needs to activate or 
deactivate all controls in a window. The field nextControl then 
serves as the link which connects all controls belonging to a 
window. 

The field contrlValue in the control record contains the 
value of the control. For simple controls this field simply 
indicates whether the control is on or off. A window can have 
several controls located in it. The application needs to know 
which one of the window's controls was pressed. This is done 
with the contrIRFCon field. 

The parameter contrIRFCon is used to store information 
about a control. This information could be an integer value that 
indexes a FORTRAN array describing the window's controls or 
ahandle to a more complex data structure on the heap. In general 
these data structures allow the FORTRAN program to distin- 
guish one control from another. For example when a mouse 
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next control 

control's window 
enclosing rectangle 

255 if visible 

highlight state 

control's current setting 
control's minimum setting 
control's maximum setting 
control definition function 
data used by controlDefProc 
default action procedure 
control's reference value 
control's title 


nextControl 
contrlOwner 
contriRect 
contrlVis 16 
contriHilite 17 
contriValue 18 
contriMin 20 
contriMax 22 
contriDefProc 24 
contriData 28 
contriAction 32 
contriIRÍCon 36 
contriTitle 40 


Figure 2. Control Record 


down event occurrsin acontrol, there is no way of knowing from 
the event record which control in the window was pressed. In the 
example program we simply number the controls 1,2, 3,4, 5 and 
set the controIRfCon field to these values. 

Window Record, A second record needed to handle con- 
trols is the window record. The controlList field of this record 
gives a handle to the first control in the window's control list. So 
if WINDOWBEG is the address of the beginning of a window 
record then LONG(WINDOWBEG+2Z'8C’) is the handle to the 
control record of the first control in a window. If there are no 
controls in a window then this value is zero. The value Z'8C' 15 
the hex value of the offset from the beginning of a window record. 
It indicates the location of the controlList field in the window 
record. For an illustration of this process see the code segment 
below the 'CASE(ACTIVATEEVT) statement in the main 
event loop of the example program. 

Event Record, Another record of interest when handling 
controls is the event record. Some examples of possible events 
are: the mouse is clicked ( a mouse down event), a window is 
drawn or erased ( an activate event), a window is covered or 
uncovered ( an update event). The individual fields of an event 
record are usually accessed with FORTRAN equivalence state- 
ments. The compiler does the work of computing offsets to 
individual fields of the event record rather than the programmer. 

The event record gives a description of the state of the 
Macintosh when the event occurred, e.g. the time in ticks since 
startup, the mouse location in global coordinates, state of the 
keyboard, etc. We are interested in the fields: where, modifiers 
and message. When a mouse down event occurrs in the content 
region of a window, the where field, after converting to local 
coordinates with GLOBALTOLOCAL, indicates the mouse 
down location in the window. For an activate event, the modifi- 
ers field indicates whether a window should be activated or 
deactivated. For an update or activate event, the message field 
gives a pointer to the window where an update or activate event 
occurred. So when implementing controls we need to access 
these fields of the event record to determine how the program 
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should respond to an event. 

All of the tool box routines that we want to use are docu- 
mented in Inside Macintosh. To use these routines from FOR- 
TRAN one needs to know how to use toolbx.sub to implement 
PASCAL calls in FORTRAN. Figure 3 gives a list of common 
PASCAL data types and their FORTRAN counter parts. This 
along with the example program should aid in implementing 
other undocumented tool box routines. 

Creating Controls 

There are several methods for creating controls in FOR- 
TRAN. The first method is to create itin FORTRAN using the 
tool box routine NEWCONTROL. Another method of creating 
a control is to read in a control resource that was compiled with 
RMAKER using the tool box routine GETNEW CONTROL. 
The programmer needs to fill in the resource id number and the 
pointer to the window the control in which will be. As in 
NEWCONTROL the routine GETNEW CONTROL retums a 
handle to the newly created control. A third method is to read in 
alist of dialog items from a resource with the routine GETNEW- 
DIALOG. 

Controls and Events 

Activate Event, When implementing a control in an appli- 
cation one needs to be concerned with three events. These are 
activate, update and mouse down events. If a user has controls 
in a window where an activate event occurs then (s)he is respon- 
sible for highlighting or unhighlighting the control. This is done 
with the tool box routine HILITECONTROL. The program- 
mer passes a control handle and a highlight code of 0 or 255 to 
HILITECONTROL where 0 means highlight (the control is to 
become active) and 255 means unhighlight. To know whether to 
highlight or unhighlight, test the first bit of the modifiers field in 
the event record. If the first bit is 1 then the window is being 
activated so the control needs to be highlighted, otherwise the bit 
is 0 and the control needs to be unhighlighted. A code segment 
to illustrate this is listed under the CASE(ACTIVATEEVT) 
section of the example program. 

Update Event. The next event of concern is the update 
event. Ап update event is passed to your application when the 
system determines that a window's contents have been changed 
and hence need to be updated. To handle an update event in a 
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INTEGER*4 

INTEGER*2 where(2) 
LOGICAL*4 

INTEGER*2 rect(4) 
INTEGER'2 

INTEGER*4 

character string of length at 
most 256, first byte contains 
length of string 


any pointer or handle 
Point 

Boolean 

Rect 

Integer 

Longinteger 

Str255 


Figure 3. Pascal/Fortran data type correspondence 
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window that contains one or more controls, one simply redraws 
the controls by passing a window pointer to the tool box routine 
DRAWCONTROLS. The window manager redraws the win- 
dow, the programmer however is responsible for redrawing the 
controls and any other contents in the window. Any outputto the 
window while updating must be bracketted by calls to BEGIN- 
UPDATE and ENDUPDATE. BEGINUPDATE clears the 
update region of the window. If these routines are not called then 
after the controls are drawn the system still thinks that the 
window needs to be updated so another update event is generated 
and the controls are redrawn and so on. The result is that the 
Macintosh "locks up" and the window contents exhibit a rapid 
flickering. 

Mouse Down Event, Thereare several types of mouse down 
events that can occur. For example the mouse can be clicked in 
a menu bar, in a system window or in the content region of an 
application window. The mouse down event in which we are 
interested is when the mouse is detected in the content region of 
an application window. In this case we need to know if it was 
clicked in a control. 

Each control belongs to a particular window. The coordi- 
nates used to express the location of the control inside the 
window must be in the window's local coordinates. When a 
mouse down event occurs, the mouse location is given in global 
coordinates by the'where' field of the event record. So the mouse 
position must be converted to local coordinates using the tool box 
routine GLOBALTOLOCAL. Next the application needs to 
call theroutine FINDCONTROL to determine if the mouse was 
pressed in a visible, active control. FINDCONTROL is passed 
the mouse location in local coordinates and a window pointer. It 
returns a handle to the selected control and the part number where 
the mouse was down if the control was visible and active, 
otherwise FINDCONTROL returns a zero. 

If FINDCONTROL determines that the mouse was 
clicked in a control then the application calls TRACKCON- 
TROL to see if the mouse is still in the control when the mouse 
button is released. If this is sothen TRACKCONTROL returns 
the part number of the control. Itis up to the application then, to 
get the value of the control with GETCVALUE, set it to a new 
value with SETCVALUE and perform the action that the appli- 
cation requires. For example if an application window has a 
scroll bar that contains text and the control is set to some new 
value then the control manager will redraw the control. The 
application is responsible for redrawing the text to reflect the new 
value of the control. 

All of these ideas are put together in the example program 
that follows. It is relatively short but it does exhibit all of the 
features necessary to implement a simple control. 

Concluding Remarks 

The tool box routine TRACKCONTROL has a calling 
argument named procPTR. The argument procPTR is a pointer 
to a procedure that TRACKCONTROL calls periodically 
while the mouse is down in a control. This is how auto scrolling 
is done. In standard FORTRAN it is not clear how you would 
pass a pointer to a FORTRAN routine through the calling list of 
TRACKCONTROL or any other tool box routine. Absoft has 
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solved this problem by writing an Assembly language "glue" 
subroutine that returns the pointer to a FORTRAN subroutine. A 
future article is needed that discusses this glue routine for 
scrolling text windows. 

[Implementation notes: In compiling and executing this 
example, we had the usual pains with the latest Microsoft Fortran 
2.1 version. Forone thing, the include statement for the menu.inc 
file produced an error! It seems someone either left out the last 
line in that include file or forgot to close the line with a ")". We 
wonder how many other include files also have bugs! Once over 
that problem, we had to get the include statements to specify the 
complete path name of the files. We gota lot of compile errors on 
this one. We finally got it to work after re-typing the path name 
inby hand, but never did really figure out what the compiler didn't 
like. Then came the wonderful HFS brain damaged linker! It 
seems the linker doesn't like complete path names. We had to 
specify a partial path name from the current level where the linker 
was located down to our file. Guess the linker can only look 
down, not up. At any rate, we finally got a compilation and 
linkage. The linker script produces an application file. And the 
compiler produces an application file! And theresource compiler 
also produces an application file, so now you have three applica- 
üon files floating about, only one of which is the "real" applica- 
tion! So becareful. We called the outputof the compiler, "control 
example apl", then called the linker output "control" and finally, 
the RMaker output, "RealControl" since it was the "real" one. As 
you can guess, we compiled, then linked in the run time library, 
and finally merged the resources in with RMaker to produce the 
final application. -Ed] 


PROGRAM CONTROLEXAMPLE 


THIS PROGRAM IMPLEMENTS SIMPLE CONTROLS IN FORTRAN 


AUTHOR: GLENN FORNEY 
DATE: 8/86 


є uM е HM м 


IMPLICIT NONE ! HELPS KEEP US OUT OF TROUBLE 


THE FOLLOWING INCLUDE FILES ARE INCLUDED WITH MS FORTRAN 
YOU SHOULD CHANGE THE PATHNAMES TO MATCH YOUR SETUP 


э »* ж ж 


include XP40-6:MacFortran: IncludeFiles: window. inc 
include XP48-6:MacFor tran: IncludeFiles:dialog.inc 
include XP48-6:MacFor tran: IncludeFiles:event. inc 
include XP48-6:MacFor tran: IncludeFiles: menu. inc 
include XP49-6:MacFor tran: IncludeFiles:control. inc 
include XP40-6:MacFor tran: IncludeFiles:quickdraw. inc 
include XP49-6:MacFor tran: IncludeFiles:misc. inc 
* DECLARATIONS 
x 
INTEGER*4 TOOLBX ! THE TOOL BOX INTERFACE 
INTEGER*4 WINDOW ! GENERAL PURPOSE POINTER 
INTEGER*2 RECTC4) ! RECTANGLE COORDINATES 
INTEGER*4 CONTROL_WINDOW ! POINTER TO THE CONTROL WINDOW 
INTEGER DUMMYHANDLE ! HANDLE TO DUMMY WINDOW 
INTEGER MENUHANDLE ! HANDLE TO MENUS 
x 
* WCONTRLLIST IS AN OFFSET THAT GIVES A 
* HANDLE TO THE FIRST CONTROL IN A WINDOW 
* HEX 8C = DECIMAL 148, SO WCONTROLLIST BEGINS AT THE 
Ж 149'TH BYTE IN THE WINDOW RECORD 
x 


INTEGER WCONTROLL IST 
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* x 
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+ 33 HM “ж 
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x 
x 
x 


е 9 HM и М 


PARAMETER CWCONTROLLIST = Z'8C') 


DECLARATIONS FOR VARIOUS EVENTS AND MOUSE DOWN LOCATIONS 


INTEGER ACTIVATE, CONTROL НАМ, SAVEPORT 

INTEGER MOUSEDOWN, UPDATEEVT , ACTIVATEEVT 

PARAMETER CMOUSEDOWN- 1,UPDATEEVT=6, ACTIVATEEVTs8) 
EVENTMASK = -1 ! PROCESS ALL EVENTS 


CLOSE MACFORTRAN 1/0 WINDOW (NEVER MAKE A DISPOSEWINDOW 
CALL ON THIS WINDOW SINCE WE DIDN'T ALLOCATE ITO 


WINDOW = TOOLBXCFRONTWINDOW) 
CALL TOOLBXCCLOSEWINDOW, WINDOW) 


INITIALIZE MENU 


MENUHANDLE = TOOLBXCNEWMENU, 1,CHARC72//"OPTIONS") 
CALL TOOLBXCAPPENDMENU, MENUHANDLE , 

+ CHARC322//" CONTROL WINDOW;DUMMY WINDOW; QUIT") 
CALL TOOLBXC INSERTMENU, MENUHANDLE , 2 ) 

CALL TOOLBXCDRAWMENUBAR ) 


READ IN CONTROL_WINDOW WITH "REGULAR" CONTROLS FROM 
RESOURCE 10 128, 0 MEANS ALLOCATE STORAGE ON HEAP, -1 
MEANS BRING WINDOW IN FRONT OF ALL OTHER WINDOWS 


CONTROL_WINDOW = TOOLBXCGETNEWDIALOG, 128,0, - 1) 


PLACE INFORMATION IN CONTROL. WINDOW'S REFCON FIELD 
TO BE USED BY APPLICATION 


CALL INITVALUESCCONTROL WINDOW , 2) 


SET UP DUMMY WINDOW TO MAKE SURE UPDATE AND ACTIVATE 
EVENTS ARE HANDLED RIGHT 


RECTC1) = 40 

RECT(2) = 30 

RECT(3) = 300 

RECT(4) = 270 

DUMMYHANDLE = TOOLBXCNEWWINDOW,O, RECT, 

+ CHARC122//"DUMMY WINDOW", . TRUE. ,4,- 1, . TRUE. , 0) 


RECTC1) = 25 ! WINDOWDRAG CONTSTRAINTS 
RECTC2) = 25 
RECTC3) = 300 
RECTC4) = 500 


MAIN EVENT PROCESSING LOOP 


IF CTOOLBXCGETNEXTEVENT,EVENTMASK ,EVENTRECORD)) THEN 


SELECT CASE (WHAT) 


CASE CMOUSEDOWN) ! HANDLE MOUSE DOWN 
CALL DOMOUSEDONWN(CWHERE , WINDOW, DUMMYHANDLE,, 
1 CONTROL. WINDOW , RECT, EVENTRECORD) 


CASECUPDATEEVT) ! HANDLE UPDATE EVENT 


MUST ALWAYS SET THE PORT TO THE WINDOW WHERE OUTPUT IS TO 
OCCUR MESSAGE IS PASSED TO US IN THE EVENT RECORD AND IS A 


POINTER TO THE WINDOW BEING UPDATED 


CALL TOOLBXCGETPORT, SAVEPORT 2 
CALL TOOLBXCSETPORT , MESSAGE ) 
CALL TOOLBXCBEGINUPDATE,MESSAGE) ! USE BEFORE UPDATE 
CALL TOOLBXCDRAWCONTROLS,MESSAGE) ! DRAW THE CONTROLS 
CALL TOOLBXCENDUPDATE,MESSAGE) ! USE AFTER UPDATE 
CALL TOOLBXCSETPORT,SAVEPORT) ! RESTORE PREVIOUS PORT 


! SAVE THE PORT 
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! SET PORT TO UPDATE WINDOW 


x 


CASECACTIVATEEVT) ! HANDLE ACTIVATE EVENT 
CALL TOOLBXCSETPORT , MESSAGE ) 
ACTIVATE = 255 ! UNHILIGHT CONTROLS 
IFCMODCMODIF IERS, 22. EQ. DDACTIVATE = Ø ! HILIGHT 
CONTROL-HAN = LONGCMESSAGE+WCONTROLLIST) ! Ist 


* LOOP THROUGH ALL CONTROLS IN A WINDOW 
x 


x 


1 


WHILECCONTROL_HAN . NE . 0) 

CALL TOOLBXCHILITECONTROL , CONTROL. НАМ, ACTIVATE) 
CONTROL_HAN = LONGCLONGCCONTROL_HAN)) ! NEXT 
REPEAT 


CASE DEFAULT 
END SELECT 
END IF 
REPEAT 
END 
SUBROUTINE DOMOUSEDOWNCWHERE , WINDOW , DUMMYWINDOM, 
CONTROL. WINDOW, RECT , EVENTRECORD ) 


* THIS ROUTINE HANDLES MOUSE DOWN EVENTS 
x 


IMPLICIT NONE 

INTEGER WINDOW, CONTROL_WINDOW, MOUSELOC 

INTEGER TOOLBX,SIZE 

INTEGER SAVEPORT, TTY_CT,WHICH_CTRL 

INTEGER*2 EVENTRECORD(8) ! OVERLYING STRUCTURE 
INTEGER*2 WHEREC2),RECTC4), INVAL_RECTC4), MENUSELEC- 


TIONC2) 


x 


LOGICAL FLAG 
INTEGER QUIT, OPTIONS,CIRCLES,MENUDATA , DUMMY , DUMMYWINDOW 
PARAMETER (QUIT=3, OPTIONS=1, CIRCLES 1, DUMMY=2) 


include XP40-6:MacFortran:IncludeFiles:window. inc 
include XP48-6:MacFor tran: IncludeFiles:menu. inc 
include XP48-6:MacFortran: IncludeFiles:control. inc 
include XP40-6:MacFor tran: IncludeFiles:quickdraw. inc 


* MOUSE DOWN LOCATIONS 
x 


INTEGER MENUBAR, SYSTEMWINDOW , CONTENTREGION,DRAGREG ION 
INTEGER GROWREGION, GOAWAYREGION, NONE 

PARAMETER CMENUBAR= 1,SYSTEMWINDOW=2, CONTENTREG ION=3) 
PARAMETER CDRAGREGION=4 , GOAWAYREGION=6 , NONE=8) 
PARAMETER CGROWREGION=5 ) 

EQUIVALENCE CMENUDATA, MENUSELECTION) 


MOUSELOC = TOOLBXCF INDWINDOW, WHERE , WINDOW) 


IF CMOUSELOC=MENUBAR) THEN 
MENUDATA = TOOLBXCMENUSELECT, WHERE) 
SELECT CASE CMENUSELECTIONC 12) 
CASE (OPTIONS)  ! THE "OPTIONS" MENU WAS SELECTED 


SELECT CASE CMENUSELECTIONC2)) 


CASE (CIRCLES) 
WINDOW = CONTROL_WINDOW 
CASE (DUMMY) 
WINDOW = DUMMYWINDOW 
CASE (QUIT) 
STOP 
END SELECT 


CALL TOOLBXCSHOWWINDOW, WINDOW) 
CALL TOOLBXCSELECTWINDOW, WINDOW) 
CALL TOOLBXCHILITEMENU, 2) 

CASE DEFAULT ! JUST PLAYING WITH THE MOUSE 
END SELECT 


ELSE IF CMQUSELOC=CONTENTREGION) THEN 
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CALL TOOLBXCSELECTWINDOW, WINDOW) 


м 


HANDLE MOUSEDOWN IN CONTROL 


CALL TOOLBXCGETPORT,SAVEPORT) |! SAVE CURRENT PORT 
CALL TOOLBXCSETPORT , WINDOW) ! SET PORT TO WINDOW 
CALL TOOLBXCGLOBALTOLOCAL,WHERE) ! TO LOCAL COORD 
CALL INCONTROL CWHERE , WINDOW) ! HANDLE IF CTRL CLICK 
CALL TOOLBXCSETPORT,SAVEPORT) ! RESTORE PORT 


ELSE IF CMOUSELOC=DRAGREGION) THEN 
CALL TOOLBXCDRAGWINDOW, WINDOW, WHERE, RECT) 


ELSE IF CMOUSELOC=GOAWAYREGION) THEN 
IF CTOOLBXCTRACKGOAWAY , WINDOW, WHERE 2) 
+ CALL TOOLBXCHIDEWINDOW, WINDOW) 
END IF 
RETURN 
END 


SUBROUTINE INCONTROL CWHERE , WINDOW) 
x 


* HANDLE EVENT IF MOUSE IS DOWN IN CONTROL 
x 


IMPLICIT NONE 
INTEGER*2 WHEREC2) 
INTEGER WHICH. CTRL,WINDOW,PART. NUMBER, IVALUE4, TOOLBX 


include XP40-6:MacFortran: IncludeF iles:control. inc 


* DEFINE SYMBOLIC NAMES FOR CONTROL ITEMS 
* NAMING CONVENTION TAKEN FROM INSIDE MACINTOSH 
x 


INTEGER INBUTTON, INCHECKBOX, INUPBUTTON, INDOWNBUTTON 

INTEGER INPAGEUP, INPAGEDOWN, INTHUMB 

PARAMETER СІМВОТТОМ= 10, INCHECKBOX=11, INUPBUTTON=20) 

PARAMETER CINDOWNBUTTON=21, INPAGEUP=22, INPAGEDOWN=23) 

PARAMETER CINTHUMB=129) 

INTEGER PUSHBUTPROC, CHECKBOXPROC, RADIOBUTPROC, SCROLL- 
BARPROC 

PARAMETER (PUSHBUTPROC=@ , CHECKBOXPROC= 1, RADIOBUTPROC=2) 

PARAMETER CSCROLLBARPROC- 16) 

INTEGER MENUBAR, SYSTEMWINDOW, CONTENTREG ION, DRAGREG ION 

INTEGER GROWREGION,GOAWAYREGION 

PARAMETER (MENUBAR= 1, SYSTEMWINDOW=2, CONTENTREGION=3) 

PARAMETER CDRAGREGION=4, GOAWAYREGION=6) 

PARAMETER (GROWREGION=5) 


IFCTOOLBXCF INDCONTROL , WHERE , WINDOW, WHICH_CTRL ).NE.® THEN 
ы IS MOUSEUP IN CONTROL? IF SO HANDLE CONTROL 


PART_NUMBER = TOOLBXCTRACKCONTROL , WHICH. CTRL , WHERE, 0 ) 
IFCPART.NUMBER . EQ. INBUTTONDTHEN 


х — BUTTON CONTROL DOES NOT NEED TO HAVE ITS VALUE CHANGED 
ELSE IFCPART_NUMBER.EQ. ІМСНЕСКВОХ )THEN 
IVALUE4 = 1 - TOOLBXCGETCTLVALUE , WHICH. CTRL ) 
CALL TOOLBXCSETCTLVALUE , WHICH. CTRL , IVALUE4) 


IF WE WERE HANDLING SCROLL BARS THEN CODE TO HANDLE MOUSE 
DOWN IN SCROLL BAR PARTS WOULD GO HERE 


* © м м 


ENDIF 
ENDIF 
RETURN 
END 
SUBROUTINE INITVALUESCWINDOW, IVALUE ) 


ж 


INITIALIZE THE REFCON FIELD OF ALL CONTROLS IN WINDOW 


IMPLICIT NONE 
INTEGER WINDOW, IVALUE, CONTROL. HAN, IVAL. CTRL 
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include XP40-6:MacFortran:IncludeFiles:window. inc 
include ХР40-6:МасҒогігап: IncludeF i les:control. inc 


x 
* HANDLE TO LIST OF CONTROLS OF THIS WINDOW 
x 


INTEGER WCONTROLLIST 
PARAMETER CWCONTROLLIST = Z'8C') 


х INITIALIZE THE WINDOW REFCON FIELD 
x 


CALL TOOLBXCSETWREFCON, WINDOW, IVALUE) 
CONTROL_HAN = LONGCWINDOW+WCONTROLLIST) ! FIRST CTRL 
IVAL_CTRL = 1 
IFCIVALUE.EQ. 12IVAL.CTRL = 129 
WHILECCONTROL HAN .NE .Q) 
CALL TOOLBXCSETCREFCON, CONTROL НАМ, IVAL .CTRL ) 
IVAL_CTRL = IVAL_CTRL + 1 


* NEXT CONTROL IN WINDOW CLAST CONTROL IN WINDOW POINTS TO 0) 
x 


CONTROL_HAN = LONGCLONGCCONTROL HAND) 
REPEAT 
RETURN 
END 


RMaker 

XP40-6 : Sof twareDev : MacFor tran :RealContro] 
APPLGPFR 

INCLUDE XP40-6:Sof twareDev :MacFortran:control 
TYPE DLOG 

, 128 
CONTROL WINDOW 
95 158 300 350 
Visible GoAway 
0 
0 

129 


ТҮРЕ DITL 
‚ 129 
4 


button 
10 20 30 58 
OK? 


button 
40 20 60 99 
Cancel 


checkBox 
70 20 90 100 
Check 


radioButton 
100 20 130 120 
Radio 


Link Script File 


f control exemple ap] 
f :Subroutines:errmsg 
f :Subroutines:toolbx 
о control 

] :fTT overlays:f77.r1 


—. 
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Fortran's World 
McFace Fixes MS Fortran 


Fortran Toolbox Access with McFace 


Most programmers who use Fortran on the Macintosh do so 
because:(1) they already know Fortran, (2) they have a lot of 
existing code that they want to run on the Mac, or (3) they want 
to add Macintosh features to existing programs. So far, the 
articles on MacFortran have dealt mainly with adding toolbox 
and Mac-specific features to Fortran programs. From earlier 
articles, it is clear that adding Mac-style features to existing 
Fortran code is not easy to do. In this article I discuss the use of 
McFace, a large, high level, *glue" subroutine that greatly 
simplifies adding Mac features to Fortran programs. 

McFace is particularly useful for porting existing Fortran 
applications, adding to the existing code the Mac "look and feel". 
Apple is now pushing "desktop engineering" and 68020 up- 
grades are becoming commonplace, so it is important to find an 
easy means to port the large body of existing Fortran engineering 
and scientific code, while adding the user interface features 
required in a good Macintosh application. 

McFace is a single, large (134K, whew!) subroutine that 
allows easy access to much of the Mac toolbox. The user 
interface is reduced to a single subroutine call with arguments 
that are used to pick out the various functions supplied by 
McFace. By making very small additions to existing Fortran 
source, it is easy to add support for the standard Apple, File and 
Edit menus, text editing of input and output streams, desk 
accessory support, and a graphics window. Graphics can be 
written to the screen and saved as Bitmaps or quickdraw pictures, 
allowing automatic handling of update events in the graphics 
window. With slightly more effort, existing Fortran can have 
dialogue boxes, alerts, and custom menus added. Conversion of 
existing programs to the event orientation of the Mac world is 
simplified. McFace also takes care of a lot of memory manage- 
ment automatically. 

McFace is an external subroutine that, when called, is auto- 
matically linked in by Fortran’s runtime linking system. Thus, 
McFace need not be explicitly linked to a Fortran program that 
is under development, but can be “hard” linked after the final 
compilation. The use of runtime linking allows multiple applica- 
tions to share one copy of McFace. McFace also has the Fortran 
Toolbx subroutine linked to itand contains resources. Because of 
this, the McFace subroutine must reside in the System folder of 
an HFS system. 

In order to show how McFace works, it is best to do an 
example. Starting with the generic Fortran code for the famous 
Sieve of Eratosthenes benchmark, we will convert it to a Mac 
interface using McFace. This is done in two stages in order to 
show the hierarchy of McFace additions that can be made to 
generic Fortran code. Unfortunately, even if you have Fortran, 
youaren't going to be able to гил any of this code unless you also 
get McFace. Therefore, I intend to show the listings in order to 
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McF ace.sub 2.1a 


illustrate how simple the code is in structure, while still letting 
you have a Mac interface on your Fortran programs. The three 
versions of the Sieve presented here are all functionally the same; 
they differ only in the user interface. To illustrate how the user 
interface changes as McFace additions are made, I have included 
copies of the output screens for each version of the program. 


How it Works 


Before diving in ana specific example, it is worthwhile to say 
afew general things about how McFace works. The main feature 
that makes the concept of McFace possible is the ability of 
Fortran to do input and output to "internal" files. That is, reads 
and writes can take place from a variable rather than from an i/o 
channel such as unit 5. McFace is able to intercept Fortran i/o by 
reassigning i/o to a specified internal file, in this case a character 
variable called MAC. McFace then acts as an intermediary that 
sits between the generic Fortran code and the new user interface 
possibilities of the Macintosh. McFace also adds a Common 
block to your applications so that communication between 
McFace and your code can be maintained through a few variables 
in Common. 

A generic call to McFace has the form: Call McFaceC 11 
integer arguments). The first argument controls whether any 
character I/O is done, and, if so, to what window. The contents 
of the character variable “МАС” are used to shuttle character 
information between your Fortran code and McFace. The next 10 
arguments are organized into 5 pairs. Each pair of numbers 
selects one of McFace's high-level functions, or macros, for 
execution. This structure can be terse anda little cryptic, but it lets 
you pack a lot of power into a single call to McFace. 

For example, the McFace call: 

Call McFaceC8, 4, 2, 3, 2, 2, -6, 0, 8, 0, 0) 

will (1) Specify no I/O because of the initial 0, (2) the 4,2 
specifies bringing a text edit window to the front, (3) the 3,2 
moves the text insertion bar to the end of the text in the window, 
(4) finally the 2,-6 causes a return to the user's code without 
updating the contents of MAC. The trailing zeroes are present 
since McFace can have up to 5 macro calls at one time. McFace 
must be called, like all Fortran subroutines, with a fixed number 
of arguments, so the last 2 unused macro slots must be zero-filled. 

Without repeating the McFace documentation this gives 
some of the flavor of how McFace is used. The calls to McFace 
look more obscure than they really are, since about 6-8 different 
combinations of macros suffice to start out converting generic 
Fortan to a Mac interface. 


Converting the Sieve 
Listing 1 shows the "generic" Sieve of Eratosthenes, as 


supplied with the compiler by Absoft. Running this program 
brings up the "glass teletype" window that is defined by the 
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Fortran runtime library. The user interface is nonexistent; what 
the user sees is unchanged from that of a conventional computer. 
The totally un-Mac-like output is shown in Screen 1. 

Listing 2 shows the same code with the modifications needed 
to attach McFace to the existing code. The modifications are 
minimal: (1) There is some initialization code (2) I/O is trapped 
and routed through McFace by using a Fortran "internal file", as 
described above. Characters are written to variable MAC rather 
than to an assigned I/O channel. Support for the standard Apple, 
File and Edit menus is automatically handled by McFace. The 
part of the code that is used to add McFace is in boldface, while 
the old "generic" Sieve code is in plain text. Screen 2 shows the 
user interface presented by the code of listing 2. For a very small 
amount of work, the user has essentially the full Mac interface! 
Much larger Fortan code can be adapted along the general lines 
shown here. The only disadvantage to this approach, as can be 
seen from the listing, is that McFace related code gets sprinkled 
throughout the old ANSI Fortran code. 

Listing 3 shows a more complete adaptation of the Sieve for 
use with McFace. Here, McFace calls are not distributed 
throughout the existing Fortran code. Instead, the Sieve program 
has been converted to a subroutine that does no I/O. Communi- 
cation with the main routine (a McFace shell) is done by passing 
an argument. This is a clean general solution to porting existing 
Fortran code to the Mac. The routines that do the real work are 
kept to simple ANSI Fortran, while McFace serves as the 
interface between the Fortran code and the Macintosh environ- 
ment. Again, McFace related codeis in boldface. Screen 3 shows 
the output of this code, which is almost identical to that of listing 
2, except for the addition of an "About Sieve" alert. The advan- 
tage of using a McFace shell with standard Fortran subroutines 
for each menu entry is that every application has essentially the 
same structure, except for the application specific menu entries 
and resources. Writing new applications becomes quite trivial, 
since the standard shell is providing all the Mac-specific support 
features. 

Notice that the use of a McFace shell allows the Sieve to be 
converted to a Menu driven system which incorporates the event 
orientation that all Mac programs should have. Events are actu- 
ally trapped by McFace, which in turn reports Menu events back 
to the Fortran program so that the appropriate part of the user's 
code is run. McFace takes care of handling Activate, Update, 
Scrolling, Auto-scrolling, Text Edit and SystemClick events, so 
that the work that is done by the application Fortran code is 
greatly reduced. 

The menus, windows and alerts in McFace are all resources. 
Therefore, further customization of the McFace environment can 
beachieved by using ResEdit on McFace'sresources. This is nice 
for adjusting size, position and title of the McFace windows. One 
can also include new resources to be used for your own alerts, as 
shown in Listing 3 and Screen 3. 


Critique 


Like any other programming tool, McFace has both strengths 
and weaknesses. Here are some of each: 

The ease of use of McFace is easily its biggest strength. To 
make the minimal modifications to the Sieve, which was the first 
thing I did with McFace, took about 20 minutes from the time that 
I first opened the documentation. 
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McFace provides enough built in functionality that writing 
new applications with McFace really takes less work than using 
the glass teletype environment supplied with Fortran. Once one 
application has been written with McFace, the subsequent ones 
are very easy. 

At 134K, McFace is not small. McFace provides a tremen- 
dous gain in functionality over plain MacFortran, but it costs a lot 
of memory. This is a trade-off that was made deliberately, since 
the use of a single subroutine is what makes using McFace so 
simple. Under switcher or with aram cache or ram disc you need 
to leave at least 256K of memory for any application that uses 
McFace. Big programs will require more. The space that McFace 
takes up on disc can be reduced by allowing more than one 
program to use McFace via Fortran's link-at-runtime capability. 

The macro commands bundle a lot of functionality into a 
single subroutine call. So much, in fact, that it is sometimes 
unclear to a naive user what all the effects of the call will be. 
However, the macro calls are well thought out, so the best way to 
learn McFace is to just dive in and try running and modifying the 
sample programs that are included. When I did not understand all 
the effects of a call to McFace, I got unexpected behavior, but no 
crashes. 

Text outputis limited to «32K because of the use of Text Edit 
Records in the text output windows. Some operations, such as 
Text Output, are slower with McFace than with a straight Fortran 
program. Speed is still acceptable, however. 

I think the "macro" commands in McFace should not ac- 
cessed by number. Instead, I think there should be a parameter 
file which uses the Fortran PARAMETER statement to define 
symbolic equivalents to the macro numbers. This is exactly what 
is done in all the Fortran include files for Toolbox access. In early 
revisions of McFace there have already been inconsistent 
changes in the macro numbers between versions, which caused 
me to recode some of my programs. Use of a PARAMETER file 
would have made converting between revisions completely 
transparent. Use of parameters would also make McFace calls 
more self documenting. A PARAMETER file should at least be 
included as an option for the user. 

Except for the size of McFace, and possibly, the use of 
parameters, these are only minor quibbles. The author, Dan 
Kampmeier is constantly improving McFace and adding features 
and functionality. He readily responds to input from users. Most 
of the deficencies of Fortran for Macintosh programming are 
eliminated by McFace. [Thank you Dan Kampmeier, for doing 
Microsoft's job! Between McFace and the CLR Libraries, maybe 
Microsoft will learn how to they SHOULD have done their 
programming products! -Ed] 


Summary 


McFace is a single external subroutine that acts as a Fortran 
"extender". With very little effort generic Fortran programs can 
be converted to run with a full Mac interface. 

The outstanding feature of McFace is its simplicity of use. 
The major drawback is the 134K of size that it adds to an 
application. However, this subroutine handles almost all of the 
Toolbox programming that you will ever need to do from Fortran. 

Conversion of existing Fortran code to a Mac interface can 
almost be reduced to a cookbook translation process, at least for 
afirst iteration. Fine tuning and addition of features is simple and 
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is added by McFace's ability to work with user designed re- 
sources. In short, if you have been frustrated by the difficulty of 
writing true Mac applications in Fortran, then McFace will 
probably solve your problems. 

McFace is available from Dan Kampmeier or Tensor labs. 
There is probably an advertisement for it in this issue of MacTu- 
tor. 


Listing 1 


x 
x Sieve of Eratosthenes 
x 
logical*2 flags(819 1) 
integer*2 i,j,k,count, iter, prime 
n = long(362) 
do 92 iter = 1,10 


! 60 Hz counter 


counts 
i=0 
do 10 i = 1,8191 
10 flagsCi) = .true. 


do 91 i = 1,8191 
if C.not. flagsCi)) go to 91 
ргіте = 1 + і +3 
count = count + 1 
k = i + prime 
if Ck .gt. 8191) go to 91 
do 60 j = К, 8191, prime 


60 flags(j) = .false. 
91 continue 
92 continue 


write (9,*) count,” primes іп”, (1010(362)-п2/60.0,” 
seconds” 

pause 

end 


Screen 1 


do 92 iter = 1, 10 


counts 
і=0 
do 10 i = 1,8191 
10 flagsCi) = .true. 


do 91 i = 1,8191 
if C.not. flagsCi)) go to 91 
prime = і + 1 +3 
count = count + 1 
k = i + prime 
if (k .gt. 8191) go to 91 
do 60 j = k, 8191, prime 


60 flags(j) = .false. 
91 continue 
92 continue 


write (МАС, 198) count, ClongC3622-n2/68 . 8 
198 FORMATCI6, ” primes in ”, f4.2, * seconds’) 
call ИсҒасе(-1,2,-6,0,0,6,0,0,0,0,0) 
pause 
end 
с 
c Include McFace Variables 
include HFS VOLUME:FORTRAN 2.2:INCLUDE 
FILES:McMenory 


Listing 3 


1899 primes in 6.733 seconds h 


Listing 2 
x Sieve of Eratosthenes 
x 


logical*2 flags(8191) 
integer*2 i,j,k,count, iter, prime 


с 
с McFace Initialization Code 
include HFS VOLUME:FORTRAN 2.2: INCLUDE 
FILES:McVariebles 
storage(232) = 18248!at least 19K of memory for 
stack expansion 
storage(249) = 3 
MAC = “About Sieve...” 
call ИсҒасев(0,2,-6,0,0,0,6,0,0,0,0) 
variables 
с 


lup to 5 text editors 
I^About Programa” 


c bring up editor 81, move insertion bar to end,return without 


reading: 
call ИсҒасе(0,4,2,3,2,2,-6,0,8,0,0) 


с 
с The code that does the work 


n = long(362) ! 68 Hz counter 


S24 


linitialize 


x 
x 


с 
с 


McFace Shell to run 
Sieve of Eratosthenes example 
integer*2 nprines 


McFace Initialization Code 
include HFS VOLUME:FORTRAN 2.2:INCLUDE 


FILES:McVariables 


st 


storage(232) = 28248 lat least 26K of memory for 
с 


аск 


storage(248) = 3 lup to 2 text editors 
МАС = “About Sieve...” 1*АЬоџі Program” 
call ИсҒасе(0,2,-6,0,0,0,0,0,0,0,0) initialize 


variables 
с 


с 


с 
с 


Add а custom menu for the Sieve 

file = ‘Sieve’ 

MAC = ‘Do Sieve;Write Test’ 

call ИсҒасе(0,-1,0,2,-6,0,6,0,0,0,0) 


bring up editor #1, move insertion bar to end, 
and return without reading: 
call ИсҒасе(0,4,2,3,2,2,-6,0,0,0,0) 


Loop that just waits for menu command 


0 
call ИсҒасе(6,0,0,0,0,0,0,0,0,0,0) 
select case (МАС) 


сазе(“Ароч%”2 lopen *About * alert 


call ИсЕасе(#, 10,4,9,0,0,0,0,0,0,0) 


caseC'Do Sieve’) 
ni = long(362) 
call SieveCnprimes) 


{ 66 Hz counter. Start 
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n2 = long(362)  ! 68 Hz counter. Stop 
deltat = (n2-n1)/68.8 
write CMAC, 198) nprimes, deltat 
198 FORMATCI6, * primes in *, 74.2, * seconds’) 
call McFace(-1,4,2,2,-6,9,9,9,8,8,8) 
case default 


end select 
repeat 
end 
Sieve of Eratosthenes subroutine 
Just generic Fortran code, converted to а subroutine 


оо 


subroutine SieveCcount) 
logical*2 flags(8191) 
integer*2 i,j,k,count,iter,prime 
n = long(362) 
do 92 iter = 1,10 
counts 
і=0 
do 10 i = 1,8191 
10 flagsCi) = .true. 
do 91 i = 1,8191 
if C.not. flagsCi)) go to 91 
primes 1+1 +3 
count = count + 1 
k = i + prime 
if Ck .gt. 8191) go to 91 


! 60 Hz counter 


do 60 j =k, 8191, prime 


60 flagsCj) = .false. 
91 continue 
92 continue 

dt = Clong(362)-n)/68.8 

return 


end 
include HFS VOLUME:FORTRAN 2.2: INCLUDE FILES :NcMemory 


File Edit Window Sieve 
Editor 1 


Rbout the Sieve... 


This is the (in)-famous Sieve of 
Eratosthenes benchmark. in many 

zw ways, а very POOR benchmark, but 
И has been run on almost all 
computers. 


Screen 3 
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Fortran's World 
Printing Hilbert Graphs 


é гие Edit 
After an extended 
absence from writing for 
MacTutor, I have found 
time to develop new ar- 
ticles using Fortran on the 
Mac. The absence arose 
from developing of an 
educational application in 
LightSpeed Pascal for use 
in my 400 level college 
course. If only Fortran 
could have that type of 
development environ- 
ment, I might never have 
switched to Pascal for 
start from scratch Mac applications. A final release version of 
that educational project should be finished by the summer (i.e., 
real soon now!). In the meantime, Microsoft released version 2.2 
in the Fall of 1986 and other individuals picked up some of the 
slack (thanks for the article on controls in the April 1987 issue). 
This month's article provides errata for Version 2.2, an overview 
ofan “Extras” disk available from Absoft, and a small application 
which illustrates using the Print Manager, pictures, and procptr's 
from within Fortran. 


Extras Disk 


Available from Absoft (the company which developed 
Microsoft Fortran for the Mac) is a disk call “Extras.” This disk 
contains additional example programs and subroutines that were 
not included in the Version 2.2 release. In particular the file 
contains: 


gpsl: An alternative spool.sub which is compatible with 

the Laserwriter. 

A Fortran source file cross referencer. 

A method for using toolbox filter procedures, in- 

cluding a sample program using scroll bars. 

An additional, more flexible, interface to 

spool.sub. Three examples are provided. 

An example program for use of the prport.sub 

routine which allows calls to the Print Manager. 

An example program of how to send a grafport to 

the printer. 

scrdump: An example program of how to dump the current 
screen to the printer. 

date: Assembly language routines for easy manipulation 


Macxrf: 
ctipre: 


splown: 
prdrag: 


gpprnt: 
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LaserWriter Page Setup v4.0 


Paper: © US Letter OA4Letter 
© US Legal 


Orientation 


Mark McBride 
Contributing Editor 
Oxford, OH 
MacTutor Vol. 3 No. 9 


== 


fortran 


Reduce or 
Q B5 Letter Enlarge: [оо] 
Printer Effects: 
[К] Font Substitution? 
[К] Smoothing? 
БО Faster Bitmap Printing? 


Fig. 1 Our Fortran Program prints Hilbert Graphs on a Laser 


of the date and time records available with the Mac. 
errata: Errata for the include files and toolbx.par files. 

If you are interested in this disk contact Absoft Tech Support 
at (904) 423-7587. [Most of these files have been placed on the 
source code disk for this issue. I find it interesting that Microsoft 
never bothered to tell anyone about these errors, or correct them! 
-Ed] Several of the files are of interest for this month's article. 
First, Listing 1 provides the errata for the include files. The last 
line of several of the include files mysteriously disappeared in the 
2.2release. Second, Listing 2 provides errors in the trap descrip- 
tors. These must be changed in both the toolbx.par file and the 
appropriate include files. One of these changes is for * HUnlock' 
which is used in this month's program. Listing 3 gives my 
modified version of the prdefs.inc file that provides definitions 
for the print record structures, used with the prprt.sub routine. 
Listing 4 gives the assembly code for the routine ctlprc.sub and 
the associated link file. This routine provides the “glue” to return 
a pointer to a Fortran procedure, which allows the use of filter- 
procs and control tracking procs. Discussion of the use of this 
routine is given below in the Hilbert graph program. In listing 5, 
is a little assembly routine to reset the randseed, since the Editor 
couldn't find a copy of a5Glob.inc that is supposed to provide 
access to the quickdraw globals. Finally, in listings 6,7 and 8 is 
the actual Hilbert program for this month! 


Hilbert Graph Program 


This month's program illustrates several Mac user interface 
features in a Fortran program: use of the Print Manager via the 
subroutine prport.sub, use of filter procedures via the subroutine 
ctlprc.sub, use of dialogs with the default button, use of pictures, 


© The Essential MacTutor, Vol. 3 


and the addition of color to your printed Imagewriter II output. 

The printgraph program has four salient features: 

1. initialization of the program structures including a ran- 
dom order hilbert curve in pict format and use of com- 
mon variables for the toolbox structures. 

2. a short event loop to detect menu selections and a 
subroutine to process the menu selection. 

3. a print subroutine which prints the hilbert picture via a 
graphport which is also Laserwriter compatible. 

4. use of a background procedure during printing which 
allows the user to cancel the print in progress 

The first two processes are straight forward and/or have been 

covered extensively in other MacTutor articles. The Hilbert 
curve is drawn using an adaptation to Fortran of an algorithm 
presented by Michael Anderson (Byte, June 1986:137-148). The 
routine draws the curve once as a picture (OPENPICTURE, 
CLOSEPICTURE). This allows the program to quickly redraw 
the graph to any grafport (window or printer) by a call to 
DRAWPICTURE. Before the picture is drawn, the order, the 
color, and the linesize of the Hilbert curve are set randomly. 

The structure of the printgraph program keeps most of the 

toolbox related variables accessible to all routines through a 
common block. The use of the common block substantially 
reduced the resulting source code, given the source code intensity 
of Fortran when using 'implicit none.' An additional advantage 
of the common block approach (at least for me) is the ability to 
keep variable declarations grouped and clear for the toolbox 
related variables. A disadvantage of the approach is that include 
files cannot contain include files, thus the toolbox .inc files must 
be listed for every subroutine. This has a tendency to increase the 
number of lines being compiled (and compile time). The source 
for the common block declarations is kept ina separate file which 
is then "included" in the main program and every subroutine 
which needs access to the global toolbox related variables. 


Printing 


MS Fortran supports printing by two basic methods. The first 
is through standard Fortran output device methods (unit=6) and 
the routine spool.sub (or the laser compatible version available 
on the ‘Extras’ disk). The second is implementation of the Mac’s 
Print Manager routines. Version 2.2 uses a 'glue' routine, 
prport.sub, (similar to toolbx.sub for toolbox calls) to provide 
access to the Print Manager. The second method enables the 
Fortran program to have the typical Macintosh printing options. 
The Hilbert program uses the second method. Extensive details 
for using the Print Manager have been provided in other MacTu- 
tor articles (March 1987 MacTutor has one recent thorough 
overview of the basics). [The prport source and object code is 
included on the source code disk. Ed] 

Use of the Print Manager involves two primary actions by the 
programmer. First, the program must maintain 120 byte printing 
record (TPrint record in Pascal, accessed via a THPrint handle or 
TPPrint pointer). The TPrint record contains most of the control 
information necessary for printing. Actually, the TPrint record 
contains several sub-records of information dealing with the 
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printer, style, band, and job information as well as a variety of 
other variables (Print Manager version, page rectangle, etc.). 
Listing 6 provides an extended version of the file prdefs.inc, 
which provides the offsets into the print record. For a complete 
list of the offsets, see Inside Mac or the March 1987 MacTutor 
article on printing. 

The various elements of the print record may be accessed via 
the MS Fortran long, word, or byte functions. For example, to 
obtain a pointer to the page rectangle from the print record you 
would: 


rPageptr = long(prrechd!l2*prInfo*rPage 


where rPageptr is the returned pointer and prinfo+rPage 
provide the offset to the print record pointer. To set the pIdleProc 
pointer you would: 


longClong(prrechdl2*prJob*tpIdleProc = canproc 


where canproc is the address of the print idle procedure (more 
below on this ability). Two key items to remember when 
accessing the print record are: first, temporarily lock the print 
record with HLOCK so that it does not move around on you 
because of a toolbox call and second, you have a handle to the 
print record. Thus, long(prrechdl) is a pointer to the start of the 
print record and long(long(prrechdl) + offsets) will return the 4 
bytes at the offset into the print record. The functions 
word(long(...)) and byte(long(...)) return 2 bytes and 1 byte 
respectively. 

Touse the Print Manager, you first need to setup a printrecord 
using NEWHANDLE vwith a size of iPrintSize. Then set the 
values of the print record to the default with a call to PRINTDE- 
FAULT. In your menu subroutine, handle a 'Page Setup' 
selection with a call to PRSTLDIALOG using the print record 
handle to set the style fields. 

Once the print command has been selected, the program 
needs to do preliminary setup work (dialogs, margins, etc.). The 
actual printing process begins with аса PRJOBDIALOG. If the 
user accepted the job dialog, the program then needs to call 
PROPENDOC. Next, print a page of material by calling 
PROPENPAGE, drawing to the printer port (with QuickDraw 
commands, e.g., TextBox, DrawPicture, DrawString), and end- 
ingapage with PRCLOSEPAGE. The page cycle continues until 
all pages have been printed. When the user selects draft (or is 
using a Laserwriter) then the material is imaged and printedas the 
page is processed. If the user selected a spooled print operation, 
then the spool file is sent to the printer via a call to PRPICFILE. 
Whenever an error occurs, the print routine needs to exit “ртасе- 
fully.’ If PROPENPAGE was called, call PRCLOSEPAGE after 
the error occurred and if PROPENDOC was called, call 
PRCLOSEDOC after the error occurred. See Apple Tech Note 
# 72 for further details on error handling and Laserwriter com- 
patibility issues. 

The Print Manager provides a useful feature in allowing 
‘background’ tasks to occur during idle time. The most common 
use of the background feature is a dialog which provides infor- 
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mation to the user about the progress of the print and allows the 
user to pause or cancel the print request. To use a background 
procedure, the pIdleProc field of the prJob sub-record of the print 
record is set to the address of the background procedure. The use 
of a procptr gives the program the flexibility to override the 
default mechanism, e.g., prssing command period. Until Absoft 
provided the assembly routine ctlprc.sub, programmers in For- 
tran were not able to implement this feature. 

The subroutine ctlprc.sub generates a pointer to a Fortran 
procedure, which can then be passed as an argument to a toolbox 
call. The calling procedure for ctlprc.sub is: 


aptrzCTLPRCC«f ilte proc name,«argument byte count?) 


where CTLPRC and aptr are both declared integer*4. The 
filter proc name must also be declared integer*4 and external. 
The byte count is the number of bytes that will be pushed onto the 
Stack by the toolbox, which is specific to the filter function being 
used. Ctlprc.sub locks itself in the Fortran heap and should be the 
first executable statement in the Fortran main program. If youare 
not going to use the procedure pointer till later, you can call 
ctlprc.sub with dummy arguments (which is what the printgraph 
program does). 

The background procedure used in the printgraph program 
looks at the event queue with GETNEXTEVENT. If there was 
akeydown event corresponding to the return key or a click in the 
cancel button of the dialog, then a print abort error is set with 
PRSETERROR. After setting the error condition, control is 
returned to the Print Managerroutine. The Print Manager routine 
detects the error and drops out of the printing process. 

The printgraph program may be easily modified to allow 
printing of text. The user will need to print the text for each 
particular page using TEXTBOX, DRAWSTRING, etc. The key 
issues the program must keep track of are line and page counts in 
order to control the by-page imaging process. 


Editor’s Notes 

[As usual, Г ve stumbled over all the things Microsoft forgot 
to put in version 2.2.In particular, they left out the include file for 
getting at the quickdraw globals. Since this programre-seeds the 
random number generator by changing the quickdraw global 
randseed, I was unable to compile the program without the 
a5Glob.inc file, which I suppose many of you may have. I tried to 
create this file from the MDS assembler equates for the qd 
globals,but was unable to come up with a Fortran equivalent that 
would run correctly. The globals are tricky because they are a 
negative offset from A5. Finally, as deadline approached, I 
simply bashed an assembly routine called reset that calls 
tickcount and resets the randseed global. That listing and the link 
file is included here. The only file you need that is not included 
isthe prport.sub listing, which was just too long. You can get that 
on the source code disk, or by contacting Absoft about their 
"Extras" disk, another item I had not heard of. Don't you just 
love how these companies go out of their way to keep you 
informed of their upgrades, bugs and omissions? А guy could 

starve on the information Microsoft sends out. ] 
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Listing 1 
Errata for Include Files 
Provided by Absoft Tech Support 


Microsoft FORTRAN Version 2.2 is distributed with several 
INCLUDE files 

to aid in the interface to the Macintosh. 
are 
incomplete. 
ing lists the 
file affected and the missing line. 
end of their 

respective file. 


Five of these files 
They а11 are missing the last line. The follow- 


Add these lines to the 


FONT . INC: 

parameter CSETFONTLOCK2Z “903 18000 ' ) 
MENU. INC: 

* SETMENUFLASH=Z ^94A 11000 ' ) 
SCRAP . INC: 


parameter (7ЕК05СКАР-7”9ҒС80000" , PUTSCRAP-Z'9FE92400' ) 


SEGMENT . INC: 
M ОЕТАРРРАКМ5-7”9Ғ536С00" , EXI TTOSHELL=Z’9F 480000' ) 


TEXTEDIT . INC: 
parameter CTESCROLL-Z ^90009400 ' , TECALTEXT2Z'9D0 10000 ' ) 


Listing 2 
Errata for Toolbox.par 
Provided by Absoft Tech Support 


ЖЖАЖЖЖАЖЖЖЖАЖАЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖҖЖХЖЖЖЖЖЖЖЖЖЖАЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 
* FUNCTION HomeResFile (TheResource: Handle) : Integer; 
INTEGER HOMERESFILE 
PARAMETER CHOMERESF ILE-Z ^9A450000 ' ) 


* FUNCTION EventAvail CEventMask: Integer; VAR TheEvent: 
EventRecord): 
x Boolean; 
INTEGER EVENTAVAIL 
PARAMETER CEVENTAVAIL=Z ^97 1CE200 ' ) 


* FUNCTION SizeResource CTheResource: Handle): Longint; 
INTEGER SIZERESOURCE 
PARAMETER CSIZERESOURCE2Z 94590000 2 


* PROCEDURE HUnlock (H: Handle); 
INTEGER HUNLOCK 
PARAMETER CHUNLOCK=Z ^02A80088 ' ) 


x r POON IURE SetItemStyle (Menu: MenuHandle; Item: 
ChStyle: Style); 
INTEGER SETITEMSTYLE 
PARAMETER CSETITEMSTYLE22^94211200' ) 


Integer; 


* PROCEDURE SpaceExtra Cextra: Integer); 
INTEGER SPACEEXTRA 
PARAMETER CSPACEEXTRA=Z ^88E 10000 ' ) 


x ыы SetResInfo (TheResource: Handle; TheID: 
TheType: ResType; Мате: Str255); 
INTEGER SETRESINFO 
PARAMETER CSETRESINFO=Z’9A9 11488" ) 


Integer; 


* Listing 3 
х Modified prdefs. inc 
x 


* (This file contains data definitions for use with the 

FORTRAN print manager interface (prport.sub). This is not а 
complete set of print manager definitions; just enough to set 
up @ basic print loop, using the print manager style and job 
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dialogs to fill out the records. See also prport. inc, 
prdrag.for. 20 Jan 86 Sent to Compuserve. EWG] 


x 


* 9 Apr 87 Modified by Mark E. McBride to add 
* additional print record offsets 
x 
* Offsets into 128 byte printing record 
x 

integer iPrVersion ! Print software ver 
parameter CiPrVersionz£) 
integer prInfo 
parameter (prInfo-2) 
integer rPaper 
parameter (rPaper=16) 
integer prSt] 
parameter (рг511-24) 
integer prInfoPT 
parameter (ргіІпҒоРТ-32) 
integer prXInfo 
parameter CprXInfo=46) 
integer prJob 
parameter CprJob=62) 
integer iPrintSize ! rec size.[120 bytes] 
parameter CiPrintSizez120) 


! PrInfo data 

! paper rect offset 
! print request’s style. 
! Time Imaging metrics 

! Print info record. 


! The Print Job request 


x 


* Offsets into prInfo subrecord 
Ж 

integer iDev ! driver info 
parameter CiDev=0) 
integer iVRes 
parameter CiVRes-2) 
integer iHRes 
parameter CiHRes-4) 
integer rPage 
parameter (rPage=6) 


! printer vert res 
! printer hor resolution 


! page rectangle 


x 
* Offsets into prJob subrecord 
x 


integer iFstPage 
parameter CiFstPage=0) 
integer iLstPage 
parameter CiLstPage-2) 
integer iCopies 
parameter CiCopies-4) 
integer bJDocLoop 
parameter (bJDocLoop-6) 
integer bDraftLoop 
parameter (bDraf tLoop-0) 
integer bSpoolLoop 
parameter CbSpoolLoop=1) 
integer iFromUsr 
parameter CiFromUsr=7) 
integer pIdleProc 
parameter CpIdleProc-8) 
integer iPrStatSize ! PrStatus rec size [26 bytes] 
parameter CiPrStatSize=26) 


! First page to print 
! Last page to print 
! copies to print 
! Printing method 
! Draft print flag. 
! Spooled print flag. 
! True from application 


! background procedure 


; Listing 4 
; ¢tlpre.sub source code 
; Provided by Absoft Tech Support 


; (Title: Toolbox Control/Filter glue procedure. Produced by: 
Absoft Soft, Inc. Date: 8/19/86 
Purpose: To interface MacFortran with the Macintosh’s Toolbox. 
Notes: This procedure takes a FORTRAN procedure as an argument 
and returns а pointer to a procedure that can be called by the 
Macintosh toolbox. This is used to allow control tracking and 
filter procedures to be written in FORTRAN. Warnings/ Limita- 
tions: This procedure locks itself into the FORTRAN heap when 
it is called for the first time. Since it returns pointers to 
locations within itself, it must never move. It should 
therefore be called as the first executable statement in the 
main program. If it is not desireable to set up the procedure 
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pointers at the begining of the main program, ctlprc can also 
be called with а zero for the procedure argument. 1 


2 
; DUMMY = CTLPRCCO, 0) 


; [This will lock the subroutine in memory without setting up 
а procedure. Calling sequence: «procedure pointer? = 
CTLPRCC«filter proc?, «argument byte count? where «procedure 
pointer?» is a FORTRAN INTEGER variable. This will be assigned 
а pointer to а procedure. This variable is then used as the 
filter procedure parameter in calls to the toolbox. «filter 
proc? is the name of the FORTRAN procedure to be called.from 
the toolbox. This should be а procedure with a single integer 
parameter, which on entry will contain a pointer to the 
arguments from the toolbox as they appear on the stack. This 
must be declared as EXTERNAL in the program unit where CTLPRC 
is used; this will usually be the main program. «argument byte 
count? is the total number of bytes of arguments that the 
toolbox will push on the stack for the type of filter proce- 
dure that this FORTRAN procedure will be used for. For 
example, if the procudure is to be used to track a scroll bar, 
the toolbox will pass 2 parameters on the stack; the control 
handle (4 bytes) and the part code (2 bytes), for a total of 6 
bytes. The track procdure should be initialized with 


INTEGER TRACK 


TRACK = CTLPRCCFTRACK, 6) 


where FTRACK is the FORTRAN procedure name. The integer 
variable TRACK will contain the address of a toolbox callable 
procedure. A maximum of 16 procedures can be set up by 
ctlprc. When this limit is reached, ctlprc will return a zero 
instead of а procedure pointer.] 


2 


INCLUDE TOOLEQU.D 


CTLPRC: 
LEA 4CA7),A4 ; Load original Stack Ptr 
LEA CTLPRCCPC),A5 ; Get exec addr 
CMPA.L Аб, А5 ; loaded in heap? 
BMI.S L1 ; If linked avoid the set. 
MOVE.W 81,-8(А12; Mark routine PERMENANT. 

L1: 
MOVE.L AQ, APPLSCRATCH*4 ; Save impure pointer. 
LEA NXTPRC,A2 ; Get addr next routine ptr. 
MOVE.L (A22,D0 ; Get offset to next routine. 
LEA PRCTBL,A1 Get pointer to proc table. 
ADD.L 00,А1 Point to next proc 
CLR.L 00 Flag no room. 
LEA . ENOPRC,^A3 Get address of table end 
CMPA.L A3,A2 Any room left? 
BGE.S NOROOM ; no 
MOVE.L A1,D0 Return proc pointer. 
MOVE.L СА4)+, А5 Get е pointer to count. 
MOVE.L CA5),D1 Get argument byte count. 
ADDQ.W #2,A1 Bypass BSR.S instruction. 
MOVE .WD1,CA1)+ Store argument byte count. 
MOVE.L (А42%,А5 Get pointer to proc. ptr. 
MOVE.L CA5)+, CA1)+ ; Store procedure pointer. 
BNE.S OKPROC ; Not nil - update offset. 
MOVEQ 80,00 ; Nil proc-flag not installed. 
BRA.S NOROOM ; бо not update offset. 


“ We We Ve We % 


њо -. We We We We 


OKPROC: ADDI.L "8,(A2) ; Offset to next proc 
NOROOM: RTS 
NXTPRC: DCL Ø 
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PRCTBL: BSR.S GLUE 
DCW Ø 
DCL 0 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW 0 
DCL 0 


BSR.S GLUE 
DCW Ø 
DCL 0 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DC.L 0 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DCL 0 


BSR.S GLUE 
OC.W 0 
DCL 0 


BSR.S GLUE 
DCW д 
DCL Ø 


BSR.S GLUE 
DCW 0 
DCL Ø 


BSR.S GLUE 
DCW Ø 
DCL д 


BSR.S GLUE 

DCW 0 

DCL Ø 
ENDPRC : 


GLUE: MOVE.L A7,A1 ; Save pointer to proc info. 
MOVEM.L 02-D7/A2-A5,-CA7) ; Save the world. 
MOVE.L APPLSCRATCH+4, Аб ; Restore impure pointer. 
MOVE.L CAG), А4 ; Restore runtime lib pointer. 
LINK A6,#-1824 ; Get an arithmetic stack. 
LEA -4(А6),А5 ; Put math stack in A5. 
MOVE.L CA1),A2 ; Get pointer to proc. info. 
MOVE.W CA2)+,-CA7) ; Save the argument byte count. 
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MOVE.L (422,42. ; Get the procedure address. 

PEA 8CA1) ; Push а pntr to arguments. 
MOVE.L A7,-CA7) ; Push а pntr to arg. pointer. 
JSR (А2) ; Call the FORTRAN procedure. 
ADDQ.W 88 А7 ; Push ergument to FORTRAN proc. 
MOVE.W CA7)+,D1 ; Get the argument byte count. 
ОМК Аб ; Return aritmetic stack. 
MOVEM.L .(A72*,D2-D7/A2-A5 ; Restore the world. 
ADDQ.W %4А7  ; Bypass pointer to procedure info. 
MOVE.L CA7)+,A1 ; Save return address. 

ADD.W D1,A7 ; Pop arguments. 

TST.W DO ; Set the condition codes. 

JMP (AD ; Return to the toolbox. 


END 
Link File for ctiprc file 
/DATA 
/TYPE е ее t 


CTLPRC.REL 
/OUTPUT ctiprc.sub 


Listing 5 Reset Subroutine 
resets the randseed qd global 


reset random seed 


"e We We We Уә 


include quickequ.d 
include traps.d 
include sysequx.d 


xdef start 

start: 
cir.) -CAT) ;clear result 
-TickCount ;get tickcount 
clr.1 D2 ;cleer 02 


move. 1 (А72%,02 ‚рор off result 
томеа.1 (сиггеп{А5),А4  ;get А5 

поуеа.1 — GrafGlobals(A4D, АЗ ;деї qd globals 
move. } 02, randSeed(A3) ;update seed 


rts 
Link File for Reset 
/DATA 
/TYPE ' ее е 
reset.REL 


pu reset.sub 


* Listing 6 
* file: PrintGraph.for 
x 


* PrintGraph Fortran Program 
x 
* Copyright (с) 1987 Mark E. McBride 


211 N. University Ave. 
Oxford, OH 45056 


Main Program 


* «е ж и ии 


program PrintGraph 


implicit none ! helps keep us out of trouble 


x 


* Reset the pathname to reflect your disk setup 
x 


include XP40-6:MS Fortran: Include Files:desk.inc 
include ХР40-6:М5 Fortran: Include Files:dialog. inc 
include ХР40-6:М5 Fortran: Include Files:event. inc 
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include ХР40-6:М5 Fortran: Include Files:menu. inc 
include ХР40-6:М5 Fortran:Include Files:memory. inc 
include ХР40-6:М5 Fortran:Include Files:misc. inc 
include ХР40-6:М5 Fortran: Include Files:quickdraw. inc 
include ХР40-6:М5 Fortran: Include Files: textedit.inc 
include ХР40-6:М5 Fortran: Include Files:utilities. inc 
include ХР40-6:М5 Fortran: Include Files:window. inc 
include ХР40-6:М5 Fortran: Include Files:prport. inc 
include XP40-6:MS Fortran: Include Files:prdefs. inc 


x 
x 
x 
x 


© 


Ж 
x 
x 


include ХР40-6:М5 Fortran: Include Files:a5Glob.inc 
Local Variables 


integer*4 mouseloc! mouse loc from FINDWINDOW 
integer*4 eventmask  ! events of interest 

integer*4 window ! to get default window closed 
integer*4 rnum,rnumi ! for use in random numbers 


Include the common variables 

include ХР40-6:М5 Fortran:printgraph.com 

lock in control proc hendler in memory 
windowsctlprc(2,0) 

Flush the event manager before calling 
eventmask = -1 

Close MacFortren 1/0 window 


windowstoolbxCFRONTWINDOW) 
call toolbxCCLOSEWINDOM, window) 


Call Text Edit and Dialog initilization. 


call toolbx(TEINIT) 
call toolbxCINITDIALOGS, 0) 


Setup а print record for use later 


prrechdlstoolbxCNEWHANDLE , iPrintSize) 
call prportCPROPEN ) 

call prportCPRINTDEFAULT , prrechd1) 
call prportCPRCLOSE > 


Setup colors array 


colors( 12233 
colors(2)=38 
colors(322205 
colors(4)=34 1 
colors(522409 
colors(6)=273 
colors(€7)=137 
co lors(8)=69 


Build the menu from the resource file 


menuhandlestoolbxCGETMENU, Apple) 

call toolbxCINSERTMENU, menuhand1e, 2) 

call toolbxCADDRESMENU, menuhandle, "DRVR") 
menuhandlestoolbxCGETMENU,F i le) 

call toolbxCINSERTMENU, menuhandle, 0) 
menuhandlestoolbxCGETMENU, Edit) 

call toolbxCINSERTMENU, nenuhand]e, 0) 

call toolbxCDRAWMENUBAR) 


setup rectangles 


call toolbxCSETRECT,rect,0,0,342,512) 
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* setup wetch cursor for later use 
x 


curshendlestoolbxCGETQURSOR, 4) 
call toolbxCHLOCK , curshandle) 
cursptrzlong(curshandle) 


call toolbxCBLOCKMOVE , cursptr, toolbx(PTR, watchC1)2,68) 


call toolbxCHUNLOCK, curshandle) 
x 


* seed the random number generator 
x 


х Jong(toolbxCGETGLOBAL )+RANDSEED )= too lbxCTICKCOUNT) 
call reset 


* Setup values for Hilbert curve 
x 


rnum=2 ! randomly set color 

do while (rnum=2) ! don’t get white 
rnum 1=too 1bx (RANDOM ) 
rnumsintCCabsCrnum 1)/32768 . 8 )*8+ 1) 

repeat 

colorpick=colors(rnum) 

rnum-toolbxCRANDOM) ! randomly set line size 

linepicksintCCebsCrnum2/32768 .0)*4* 1) 

rnum-2 

do while (rnum«3) 
rnuml-toolbxCRANDOM) ! randomly set Hilbert order 
rnumsintCCabsCrnum12/32768.0)*6* 1) 

repeat 

n=rnum 


call Drawing 
x 


* main event processing loop 
x 


do 
x 


* handle system jobs 
x 


call toolbxCSYSTEMTASK) 


x 


* handle events 
x 
if CtoolbxCGETNEXTEVENT, eventmask,eventrecord)) then 
select case (what) 
case (1)! mouse down 
mouseloc = toolbx(FINDWINDOW, where, window) 
if (mouselocs1) then ! in menu bar 
call menus 
else if (mouseloc-2) then ! systemwindow 
call toolbxCSYSTEMCLICK, eventrecord, window) 


end if 
cese default ! ignore other events 
end select 
end if 
repeat ! repeat for another event 


x 


* end of the main program 
x 


end 


x 


* menus: mouse down event detected in menu area 
x 


subroutine menus 

implicit none 
* Reset the pathname to reflect your disk setup 
x 


include ХР40-6:М5 Fortran: Include Files:desk.inc 
include XP40-6:MS Fortran: Include Files:dialog. inc 
include ХР40-6:М5 Fortran: Include Files:event. inc 
include ХР40-6:М5 Fortran: Include Files:menu.inc 
include ХР40-6:М5 Fortran: Include Files:memory. inc 
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include ХР40-6:М5 Fortran:Include Files:quickdraw. inc 
include ХР40-6:М5 Fortran:Include Files:misc. inc 
include XP40-6:MS Fortran: Include Files: textedit.inc 
include ХР40-6:М5 Fortran:Include Files:utilities. inc 
include XP48-6:MS Fortran:Include Files:window. inc 
include ХР40-6:М5 Fortran:Include Files:prport. inc 
include ХР40-6:М5 Fortran: Include Files:prdefs. inc 


include ХР40-6:М5 Fortran: Include Files:0SUtilities. inc 
include ХР40-6:М5 Fortran: Include Files:scrap. inc 


x 


є * 


x 
x 


local variables for menu subroutine 
character*88 name, pname 
integer*4 refnum, item4,i,j,size,count 
integer*2 OSErr 
logical ok 

variable for conversion to pascal type strings 
character*256 str255 

variables for making menu selections 
integer*2 menuselection(2) ! menu select info 
integer*4 menudata! for use left of equals sign 
equivalence (menuse lection, menudata) 

Include the common variables 


include XP40-6:MS Fortran:printgraph.com 


Start of Subroutine 


menudata-toolbxCMENUSELECT , where) ! get 


selected menu data 


і tem4=menuse lect ion(2) 


bytes 


select case (menuselection(1)) 


menu? 


case (File) ! File menu 
menuhand 1 e=too 1bx(GE TMHANDLE, File) 
select case (menuselection(2)) 
case(PSetUp)! Page Setup selected 
call prpor tCPROPEND 
ok=prpor tCPRSTLDIALOG, prrechd1) 
call prportCPRCLOSE) 
case(PrintPic) ! Print Hiblert curve selected 
call PrintIt 
case(Quit) ! Quit selected 
stop 
case default 
end select 
case (Apple) ! Apple menu 
menuhandlestoolbxCGETMHANDLE , Apple) 
select case(menuselection(2)) 
caseCAbout)! About item selected 
call toolbxCGETPORT,oldPort) 
dig=toolbx(GETNEWDIALOG, 200,0, - 1) 
call toolbxCSETPORT,d1g) 
call FrameDItem 
ditemhz 
while Cditemh o 1) 
call toolbxCMODALDIALOG, 0 , di temh) 
repeat 
call toolbxCSETPORT,oldPort) 
call toolbxCDISPOSEDIALOG, dlg) 
case default  ! desk acc selected 
call toolbxCGETITEM,menuhandle, item4, пате) 
refnum-toolbxCOPENDSKACC , name) 
end select 
case (Edit) ! Edit menu 
if C.not. toolbxCSYSTEMEDIT, item4-1)) then 
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! convert to 4 


! which 


end if 
case default ! just playing with the mouse 
end select 
call toolbxCHILITEMENU, 0) 


end 


Drewing: create hilbert picture of order n using 
recursive techniques. This is an 
adaptation of Michael Ackerman's 
algorithim given in Byte, June 1986, 
pages 137-148. 


зе е 20 20 ум М 


subroutine Drawing 


implicit none 
x 
* Reset the pathname to reflect your disk setup 
x 
include ХР40-6:М5 Fortran: Include Files: quickdraw. inc 
include ХР40-6:М5 Fortran: Include Files:memory. inc 
include ХР40-6:М5 Fortran: Include Files:misc.inc 
include ХР40-6:М5 Fortran: Include Files: window. inc 
x 


* include common variables 
x 


include ХР40-6:М5 Fortran:printgraph.com 


call toolbxCSETCURSOR , watch) 

call toolbxCSETRECT,rect,0,0,342,512) 
pichandlestoolbxCOPENPICTURE, rect) 
call toolbxCFORECOLOR,colorpick) 

call toolbx(BACKCOLOR, colorsCWhite2) 
call toolbxCPENSIZE, l inepick, linepick) 
rder=n 

9у-512/((2%%гдег-12%12) 


turnz-1 

дх=0 

х= 10 

у= 10 

call toolbxCMOVETO, 10, 10) 
call Greph 


call toolbxCCLOSEP ICTURE) 


call toolbxCFORECOLOR, colors(Black)) 
call toolbxCPENSIZE, 1, 1) 

call toolbxC INI TCURSOR) 

end 


x 
* Graph: draws a hilbert curve 
x 


subroutine Graph 


implicit none 
x 
* Reset the pathname to reflect your disk setup 
x 
include ХР40-6:М5 Fortran: Include Files: quickdraw. inc 
include ХР40-6:М5 Fortran: Include Files: window. inc 
x 


* include common variables 
x 


include ХР40-6:М5 Fortran:printgraph.com 
integer*4 temp 


rder=rder- 1 

turnz-turn 

temp=dy 

dy=- turn*dx 

dx=turn* temp 

if (rder.gt.0) call Graph 
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x=x+dx 
y=ytdy 
call toolbxCLINETO, х,у) 
turn=-turn 
temp=dy 
dy=- turn*dx 
dx=turn* temp 
if (гдег.0%.02 call Graph 
x=x+dx 
y=ytdy 
call toolbx(LINETO,x, y) 
if (rder.gt.0) call Graph 
temp=dy 
dy=- turn*dx 
dx=turn* temp 
turn=-turn 
x=xtdx 
y=ytdy 
call toolbx(LINETO, x,y) 
if (rder.gt.@) call Graph 
temp=dy 
dy=- turn*dx 
dx=turn*temp 
turn=-turn 
rder=rder+1 
end 
x 


: Subroutine to print out contents of graph window 
Subroutine PrintIt 
implicit none 

: Reset the pathname to reflect your disk setup 


include XP40-6:MS Fortran: Include Files:quickdraw. inc 
include ХР40-6:М5 Fortran: Include Files:dialog. inc 
include ХР40-6:М5 Fortran: Include Files:memory. inc 
include XP48-6:MS Fortran: Include Files:misc. inc 
include ХР40-6:М5 Fortran:Include Files:window. inc 
include ХР40-6:М5 Fortran: Include Files:prport. inc 
include XP40-6:MS Fortran:Include Files:prdefs. inc 

x 


* other local variables 
x 
integer*2 qfleg ! Variable to hold bjDocLoop flag 
integer*4 temp, i 
integer*2 srect(4),margins(4) 
integer*4 rPageptr 
logical ok 
integer*4 canproc 
x 


* variable for conversion to pascal type strings 
x 


character*256 str255,str1 
x 


* print manager structures 
x 


integer*4 theprport ! Pointer to printer grafport 


integer*1 thestrec(26)  ! Status rec for PRPICFILE 
x 


* include common variables 
x 


include XP40-6:MS Fortran:printgraph.com 
x 

* start print job 

x 


call toolbxCHLOCK, prrechd1) 
ok=. false. 
call prportCPROPEN) 
ok=prport CPRJOBDIALOG, prrechd] ) 
if Cok) then 

x 


* set up idle proc 
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call toolbxCGETPORT,oldPort) 

call toolbxCSETCURSOR , watch) 
canproc=ctlprc(f track, 0) 

longClong(prrechd! )+ргЈоб+рІа1еРгос)=сапргос 


rPageptr-long(prrechdl)*prInfo*rPage 
call toolbxCBLOCKMOVE , rPageptr, too lbxCPTR, srectC122,8) 


dlg-toolbxCGETNEWDIALOG, 1818,8,-1) 

str l=str255( ‘Hilbert Order '//char(48*n)) 
call toolbxCPARAMTEXT, str 1, ^ ^, ^^, '?) 

call toolbxCDRAWDIALOG, dlg) 

call toolbxCSETPORT,d1g) 

call FrameDI tem 


call toolbxCINITCURSOR) 
x 
* start printing 
x 
theprport = prport(PROPENDOC, prrechdl, 0, 0) 
if CprportCPRERROR) .NE. Ø) then 
write(9,*) “Printer error *,prportCPRERROR) 
goto 10 
endif 
call prportCPROPENPAGE, theprport, 6) 
if CprportCPRERROR) .NE. Ø) then 
write(9,*) "Printer error *,prportCPRERROR) 
goto 20 
endif 
call toolbxCDRAWPICTURE, pichandle,rect) 
20 call prportCPRCLOSEPAGE, theprport) 
10 call prportCPRCLOSEDOC, theprport) 
qf lag = byteClongCprrechd1)+prJob+bUDocLoop) 


If the print method is spooled, the actual printing 
still needs to be done. 
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if CCqflag = bSpoolLoop) .AND. CprportCPRERROR) = 022 
then 
call prport(PRPICFILE, prrechdl, Ø, Ø, Ø, toolbx(PTR, 
thestrec)) 
endif 


if (prportCPRERROR) .NE. Ø) then 
write(9,*) “Printer error ",prportC(PRERROR) 
endif 
call toolbxCDISPOSEDIALOG, dlg) 
call toolbxCSETPORT ,oldPort) 
endif 
call prportCPRCLOSE) 
call toolbxCHUNLOCK, prrechd1) 
end 


ж” 


Frame rounded rectangle, sets the default item 
subroutine FrameDI ten 

implicit none 

: Reset the pathname to reflect your disk setup 


include ХР40-6:М5 Fortran: Include Files: quickdraw. inc 
include ХР40-6:М5 Fortran: Include Files:dialog. inc 
x 


* include common variables 
x 


include ХР40-6:М5 Fortran:printgraph.com 
x 


* local variables 
x 


integer*4 dLog 
integer*2 1Вох(4) 
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integer*4 iBox4(4) 
integer*2 iType 

integer*4 iHandle 
integer*1 oldPenState( 18) 


call toolbxCGETPENSTATE, oldPenState) 

call toolbx(GETDITEM, dlg, 1, iType, iHandle, iBox) 
call toolbxCINSETRECT, iBox, -4,-4) 

call toolbxCPENSIZE,3,3) 

call toolbxCFRAMEROUNDRECT, iBox, 16, 16) 

call toolbxCSETPENSTATE, oldPenState) 


end 


str255: converts а FORTRAN string to a 
Pascal LSTRING 


е эе * и 


character*256 function str255(string) 
character*(*) string 


str255 = charClenCtrim(string)))//str ing 


end 


* (This is the idleProc for the Print Manager used in the 
printit subsubroutine. Normally, a pointer to the arguments 
passed to а control proc routine by the toolbox is passed in 
ergptr. This is done since the glue routine used by ctlprc to 
interface the toolbox to FORTRAN has no way of knowing what 
kind of procedure this is (control actionProc, dialog filter- 
Proc, etc.), and therefore no way of knowing how many parame- 
ters to expect. argptr points to the last argument (partCode) 
as pushed on the stack by the toolbox; preceding arguments are 
at higher addresses. ] 


subroutine ftrackCargptr) 


implicit none ! Declare all variables. 
integer argptr ! Pointer to arguments. 
! but there are none 
logical bool 
integer*2 item 
integer*4 cancelitem 
integer*4 digptr, toolbx 
integer*4 mDownMask , KeyDownMask , keyDown 
parameter (cancelitem=1) 
parameter (mDownMask=2,KeyDownMask=8 , keyDown=3 ) 


integer*2 theEvent(8) 
integer*2 what 
integer*4 message 
integer*4 when 
integer*2 where(2) 
integer*2 modifiers 


x 
* Reset the pathname to reflect your disk setup 
x 


include ХР40-6:М5 Fortran: Include Files:event. inc 
include ХР40-6:М5 Fortran: Include Files:dialog. inc 
include ХР40-6:М5 Fortran: Include Files:prport. inc 
include ХР40-6:М5 Fortran: Include Files:prdefs. inc 


bool=toolbx(GETNEXTEVENT , mDownMask+KeyDownMask, theEvent) 

item=0 

if CCwhat=keyDown).and.CmodCmessage, 256) = 13)) then 
item-cancelitem 

else if toolbxCISDIALOGEVENT, theEvent) then 
boolstoolbxCDIALOGSELECT, theEvent,dlgptr, item) 

end if 

if Citem=cancelitem) then 
call prportCPRSETERROR, 128) ! set abort error 

end if 
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return 
end 


* Listing 7 
x file: PrintGraph.corm 


x 


* PrintGraph Fortran Program 

x 

* Copyright (с) 1987 Mark E. McBride 

x 211 N. University Ave. 
х Oxford, OH 45056 


x 

* This file contains variable definitions 

* that will be common to the main program and 
* the non-print related subroutines. 

* These include most of the toolbox structures 


* used throughout the program 
x 


x 
* general and toolbox variables 
x 


integer*4 toolbx ! toolbx.sub interface 

integer*4 prport ! print manager interface 

integer*4 ctlprc ! Create toolbox callable procs. 
integer*4 n,dy,dx,x,y,turn,rder ! Hilbert curve variables 
integer track ! Address of the track proc. 

integer ftrack ! This keeps IMPLICIT NONE happy. 


* Declare ftrack as a subroutine. 
external ftrack 


x 


* handles 

x 
integer*4 menuhandle ! handle to menu 
integer*4 pichandle ! handle to picture 
integer*4 oldPort ! handle to oldport 
integer*4 curshandle,cursptr ! handle to cursor 
integer*1 watch(68) ! watch cursor record 

x 


* print manager structures 
x 


integer*4 prrechdl! Handle to print record 
integer*4 theprport  ! Pointer to printer grafport 
integer*1 thestrec(26)  ! Status rec PRPICFILE 

x 


* dialog structures 


x 

integer*4 dlg, itemno, itemhd] ! general purpose dialog 
pointer 

integer*2 ditemh, itemtype І item hit in dialog 


x 


* event strucutures 

x 
integer*2 eventrecord(8) ! overlying structure 
integer*2 what ! type of event 
integer*4 message ! extra event information 
integer*4 when ! time of event in 68ths of seconds 
integer*2 where(2)! mouse loc in global coordinates 
integer*2 modifiers ! mouse button and modkeys 

x 


* Menu and other selection constants 
x 
integer*4 Apple,File,Edit 
integer*4 About 
integer*4 PSetUp, PrintPic, Quit 
integer*4 Undo, Cut, Copy, Paste, Clear, ShowCl ip 
integer*4 Black, White,Red,Green,Blue, Cyan,Magenta, Yel low 
integer*4 top, left,bottom,right 
x 


* Colors and line size 
x 


integer*4 colors(8) 
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integer*4 colorpick 
integer*4 linepick 


parameter CApple=29,File=30,Edit=31) 

parameter CAbout=1) 

parameter (PSetUp=1,PrintPic=2,Quit=4) 

parameter CUndo=1,Cut=3, Copy=4,Paste=5,Clear=6, ShowClipz8) 
parameter (Black=1,White=2,Red=3,Green=4,Blue=5, Cyan=6) 
parameter (Magenta=7, Yel low=8) 


Link File 


* This is the Link File 
* for the PrintGraph Program 


* Rectangles for general use 
x 
integer*2 rect(4),rect 1(42,rect2C4D,rect3C4) 


* common variable sets 
x 
common /seti/menuhandle,pichandle,rect,rect1, rect2,rect3, 
+ prrechdl,theprport, thestrec,dlg, i temno, 
itemhdl,ditemh, 
+ itemtype,eventrecord(8),toolbx,ctIprc, track,ftrack, 
+ prport,n,dy,dx,x,y, turn,rder,colorpick, linepick, 
+ curshandle,cursptr,watch,colors,oldPort 


o PrintGraph 

f PrintGraph ap] 
f prport.sub 

f ctlprc.sub 

f toolbx.sub 

f reset.sub 

1 fTT.r1 

g 


x 


* parameters 
x 


parameter Ctop=1, lef t=2, bot tom=3,right=4) 
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Fortran's World 
Dialog Filter Procs for Fortran 


ModalDialog Filter Procs from MS FORTRAN 

When writing code in MS FORTRAN, it is occaisonally 
necessary to have a pointer to a piece of code to pass to atoolbox 
call -a proc pointer. Absoft has provided a glue routine called 
ctlprc to perform this function. Ctlprc has a limitation in that it 
does not return anything on the stack, which is necessary for im- 
plementing a filter proc for ModalDialog. An assembly language 
glue routine for this is described herein. 

ModalDialog filter procs are called each time ModalDialog 
gets an event from GetNextEvent (note that the event mask 
excludes disk insert and application events). It passes a pointer to 
the FrontWindow, and two VARs; the EventRecord and the 
ItemHit. Note that VARs are longword addresses to the data 
structures, which is exactly how FORTRAN passes calling 
arguments. ModalDialog expects the filter proc to return a 
Boolean result; True if ModalDialog should process the event, 
and False if the filter proc has done so already. A Boolean result 
should be passesd as a word on the stack above the calling 
arguments, and this is where ModalDialog expects to find it. 
FORTRAN passes calling arguments as long word addresses, 
and ctlprc restores the stack on return from the called procedure. 
Function results are passed register DO, and ctlprc trashes this 
register. Thus, we must write some assembly code to fix this if we 
want to write our filter proc in FORTRAN. The following MDS 


code does just that. 
XDEF xfilt 
INCLUDE MacTraps.D 
INCLUDE SysEqu.D 
INCLUDE ToolEqu.D 
INCLUDE QuickEqu.D 
; Xfilt is the initialization code. It stores address of the 
; FORTRAN subroutine returned from ctlprc and returns а proc 
; pointer whch can be passed to ModalDialog. 
xfilt: 


MOVEM.L A@-A1,-CSP) ;Save registers 


MOVE.L — 16CSP2,A0;calling FORTRAN passes 

LEA service,A1 ; ptr to filter subroutine 
MOVE.L САЙ), CAD; which we store locally 

LEA action,A2 ;glue procedure address 

MOVE.L 12(5Р),А1;15 returned 

MOVE.L А0,С(А1) ; to FORTRAN on the stack 
MOVEM.L (SP2*,A0-A1 Registers restored 

RTS 


; Action is the proc which gets called by ModalDialog. It 
; massages the stack after FORTRAN finishes with it so that 
; Boolean result can be returned to ModalDialog. 


action: 
MOVEM.L А1/00,-СӨР) ;Save registers 
PEA result ;Pass FORTRAN an address 


; to store the BOOLEAN result 
Clone the stack 


MOVE.L  24(5Р),-(ӨР) ;Dg_ptr 

MOVE.L 24(5Р),-(ӨР) ;Event record 

MOVE.L  24C(SP),-(SP) ;ItemHit 

MOVE.L ѕегуісе,А1 /10а0 pointer to FORTRAN 

JSR CAI) ; routine and call it 
536 


Jeff Mandel 

Tulane University Hospital 
New Orleans, LA 
MacTutor Vol. 3 No. 12 


;get function result and place on stack where ModalDialog 
expects it 
MOVE.W  result,24CSP) 
MOVEM.L (SP)+,A1/D8  ;restore registers 
; Fix the stack so that we can RTS 
MOVE.L (SP)+,8CSP)  ;move return address 
ADD.L 88 SP ;fix stack pointer 
RTS 
; Declare some local storage (note that this makes the code 
; Non-reentrant) 
service DC.L6 
result DC.WO 
end 


nd 


fortran 


The following MDS link file will make a file that the 


FORTRAN linker can deal with: 
; File xfilt.Link 

/Data 

/Type ‘8208’ '0000" 

Ixfilt 

/Output xfilt.sub 

[ 


xf ilt 
$ 


Next, we set up the pointers in the main program: 
PROGRAM WHIZBANG 
implicit none ! FORTRAN discipline 
integer ctlprc , my filter , filter_] , my_filter_ptr 
external ctlprc , my-filter 
filter 1 = ctlprc С my filter , 16 )!Four long words of 

larguments 

call xfilt € filter_i , my_filter_ptr 2 


Note that the call to ctlprc should be performed before any 
statements which allocate memory. The FORTRAN filter rou- 
tine, my_filter should be appended to the main program. This 
simple filter routine handles carraige returns in a non-standard 
way. 
subroutine my_filter С argptr ) 

implicit none 

integer Dg-ptr , ItemHit.ptr , ev_ptr , argptr , result.ptr 

integer i , char.code , toolbx 

integer*2 ItemHit 

logical handle_event 

integer*1 еуепігесогас 16) 

integer*2 what 

integer*4. when 

integer*2 where(2) 

integer*2 modifiers 

integer*4 message 

equivalence С eventrecordC1) , what ) 

equivalence С eventrecord(3) , message ) 

equivalence С eventrecord(7) , when ) 

equivalence С eventrecord(11) , whereC1) ) 

equivalence € eventrecord( 15) , modifiers ) 

integer eDefltem , editField 

parameter ( aDef Item = Z’A8', editField = Z'M' ) 

result.ptr = long C argptr + 12 ) 

Dg.ptr = long С argptr + 8 ) 

ev_ptr = long С argptr + 4) 

ItemHit_ptr = long С argptr 2 
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doCist, 16) 
eventrecord Ci) = byte C ev ptr + і - 1) 

repeat 

if С what .eq. 3 ) then !key down 
C If user hits return or enter key, check the default item 
C number. If zero, then return with ItemHit as the active edit 
С text field. If default item is nonzero, return it as the ItemHit. 

char_code = message .and. Z'000000FF"' 
if С char_code .eq. 13 .or. char code .eq. 3 ) then 
if € word С Dg.ptr + aDefItem ) .eq. Ø ) then 
ItemHit = word С Dg_ptr + editField ) + 1 
handle_event = .false. 
else 
ItemHit = word С Dg_ptr + eDefItem ) 
handle_event = .false. 
end if 
else 
handle.event = .true. 
end if 
else 
handle event = .true. 
end if 
if С handle_event ) then 
word € result.ptr ) = 2’@' 
else 
word С result ptr ) = z’FFFF’ 
word € ItemHit_ptr ) = ItemHit 

end if 

return 

end 
Finally, we call ModalDialog with our proc pointer: 

done = .false. 

do while С .not. done ) 

cell toolbx С MODALDIALOG , my-filter. ptr , ItemHit ) 
select case ( ItemHit ) 

[useful code] 
end select 

repeat _ | 

Note that if you are using this scheme to allow your program 
to do background processing while you are waiting for the user 
to choose to do something from a modal dialog box or alert, this 
code should execute when a null event (what=0) is detected, and 
should pass the event to ModalDialog (handle event-.true.) if 
you want the text insertion point to blink. Also, if you want to 
handle your own application events, call GetNextEvent in the 
filter proc with EventMask = Z’F000' (so it doesn't steal dialog 
events). 

Please note that this article is not an epistle for FORTRAN 
as a programming language, just some help for those of us who 
have too much invested in FORTRAN to move to Pascal or C. 

[A complete simple demo using this filter proc from Fortran 
is available on the MacTutor source disk for this issue. Here is 
the fortran source for this demo. Insert the filter code above into 
this program. -Ed] 

PROGRAM WHIZBANG 

implicit none 

integer aDefItem 

parameter ( aDef Item = Z'A8' ) 

integer ctlprc , my-filter , filter_1 , my_filter_ptr 

external ctlprc , my filter 

integer get_dit , result , dialog_ptr , toolbx 

integer top_field , bottom field , result field , end_dialog 

parameter С top field = 12 

parameter С bottom field = 

parameter ( result field = 

parameter С end. dialog = 

integer TEINIT 


parameter СТЕІМІТ-779СС00000"2 
integer GETNEWDIALOG, DISPOSDIALOG, INITDIALOGS 


2) 
3) 
4) 
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integer MODALDIALOG 
parameter CGETNEWDIALOG-Z '97C8A400 ' , 
+ DISPOSDIALOG-Z 98310000 ' ,MODALDIALOG=Z 99116000 ' ) 
parameter CINITDIALOGS=Z’97B 100002 
INTEGER HIDEWINDOW 
PARAMETER CHIDEWINDOW=Z “9 1610000 ' ) 
INTEGER FRONTWINDOW 
PARAMETER CFRONTWINDOW-Z/92480090' 2 
integer*2 ItemHit 
logical done 
filter-1 = ctlprc C my_filter , 16 )!Four long words 
larguments 
call xfilt C filter_1 , myfilter_ptr ) 
done = .false. 
call toolbx CTEINIT) 
call toolbx € INITDIALOGS , Ø ) 
call toolbx € HIDEWINDOW , toolbx С FRONTWINDOW ) ) 
dialog_ptr = toolbx С GETNEWDIALOG , 100 , Ø , -1) 
word С dialog_ptr + aDefItem 2 = 0 
do while С .not. done ) 
call toolbx С MODALDIALOG , my filter ptr , ItemHit ) 
select case ( ItemHit ) 
case ( top_field ) 
result = getdit С top field , dialog ptr ) 
call setdit € result , result. field , dialog. ptr ) 
case С bottom field ) 
result = getdit ( bottom field , dialog.ptr ) 
result = result * 10 
call setdit € result , result. field , dialog.ptr ) 
case ( end.dialog ) 
call toolbx C DISPOSDIALOG , dialog.ptr ) 
done = .true. 
case default 
continue 
end select 
repeat 
end 
integer function get dit С item num , dg_ptr ) 
inplicit none 
integer toolbx , item лит , dg.ptr ,itemhandle 
integer itemp , ktemp 
charecter*256 temp , dgtext 
integer*2 ItemType , box (4) 
integer GETDITEM , GETITEXT 
parameter ССЕТОІТЕМ=2 ^980 11080', СЕТІТЕХТ-7”990 16000 ) 
call toolbx (С GETDITEM , dg.ptr , item.num , 
x ItemType , itemhandle , box ) 
call toolbx € GETITEXT , itemhandle , dgtext ) 
itemp = ichar С dgtext (1:1) 2 + 1 
ktemp = 0 
if С itemp .gt. 1) then 
temp = dgtext ( 2 : itemp ) 
read ( temp , * , err = 100 ) ktemp 
end if 
get_dit = ktemp 
return 
190 get dit = 0 
return 
end 
Subroutine set dit € value , item num , dg.ptr ) 
implicit none 
integer toolbx , item. num , dg.ptr , ItemType , itemhandle 
integer value 
integer*2 box (4) 
character*256 dgtext 
integer GETDITEM , SETITEXT 
parameter ССЕТОІТЕМ=2 ^98р 11080', SETITEXT=Z’98F 16000' ) 
write С dgtext , * ) value 
dgtext (1:1) = char ( len С trim C dgtext) 2 - 1) 
call toolbx ( GETDITEM , dg.ptr , item num , 


x ItemType , itemhandle , box ) 
call toolbx С SETITEXT , itemhandle , dgtext ) = 
return oe} 
end TAN 
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Scheme Does Windows! 


Programming a Text Editor in 
MacScheme+Toolsmith™ 

The purpose of this article is to give an example of an 
application written in MacScheme+Toolsmith™. The applica- 
tion is a simple text editor, similar to the text editor written in 
Pascal that appears elsewhere in this issue of MacTutor. This 
editor is incomplete in many ways. It does not support the 
Clipboard, for example, nor does it check to make sure that the 
edited text does not exceed the limits of a single text edit record. 
It does, however, convey a sense of what it is like to program 
using MacScheme+Toolsmith. The code for this editor is a pre- 
release version of an example included with 
MacScheme+Toolsmith. A screen shot of the program is shown 
in figure 1. The program loads and saves files (which the Pascal 
version in this issue doesn't), and includes a find and change 
function. 

About MacScheme, MacScheme+Toolsmith 

MacScheme™ is a Lisp system from Semantic Microsys- 
tems that runs on 512K and larger Macintoshes and includes an 
editor, incremental byte code compiler, debugger, and tracer. 
MacScheme implements the Scheme dialect of Lisp, a dialect 
known for its simplicity, regularity, and power. Aside from 
simple quickdraw graphics routines, however, the only way to 
access the Toolbox from MacScheme was by using machine 
code. This was one of the motivations behind a new product 
called MacScheme+Toolsmith. 

MacScheme+Toolsmith lets you program the Macintosh 
Toolbox interactively in Lisp. It provides Lisp access to the 
complete setof Toolbox traps and high level routines for creating 
window and menu objects. (Youcan bring upa textedit window 
with a single line of code, interactively.) Source code for the 
object-oriented window and menu routines is included so you 
can modify them if you want. MacScheme+Toolsmith supports 
multitasking and provides an interrupt system for handling 
events. 

MacScheme+Toolsmith is being released in December 
1986. To use the high level window and menu routines, 1 M 
RAM is needed. Youcan use the rest of MacScheme+Toolsmith 
with only 512K. 

The Text Editor Program 

Scheme programs consist of definitions mixed with expres- 
sions. These definitions and expressions are executed in order, 
just as if they were typed interactively. The first expression that 
appears in the editor program sets some variables that tell the 
compiler not to include documentation for source code and 
arguments. The second expression loads a number of files from 
the MacScheme+Toolsmith disks containing definitions of pro- 
cedures and data used by the program. 
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Deer Ralph, 


I'm looking forward to seeing you in е few weeks, and to seeing what fii: 
you're doing with your new Macintosh Plus 1 hope the weather in Houston [| 
is better then it is in Beaverton, Oregon these days! It's been raining all 
sorts of things for weeks now. My driveway is covered with creature 
that used to be baby slugs and are rapidly assuming larger proportions. 
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E This tent editor was crested by E 
EM the accompanying MacScheme e 
code. 


Figure 1: Our Lisp version Text Editor 

Figure 2 shows the files in the "Chapters" folder which 
correspond to chapters in Inside Macintosh. Thus "chap20.data" 
contains the type declarations for the standard file package 
described in chapter 20 of Inside Macintosh, while 
"v2.chap4.traps" contains the low level file manager traps de- 
scribed in chapter 4 of volume II of Inside Macintosh. By this 
neat packaging trick, you can easily find the Scheme definition 
for trap calls as you study the toolbox documentation in Inside 
Macintosh. 

The files in the "Examples" folder shown in figure 3 are 
examples included with MacScheme+Toolsmith. The file 
"fs.sch" contains high level file system calls analogous to the 
Pascal calls documented in Inside Macintosh, and the file 
"files.sch" contains even higher level calls for prompting for, 
reading, and writing entire files. The file "fonts.sch" defines 
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Figure 2: The Scheme Trap Docs 
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Figure 3: Our Editor Files 
some general purpose procedures for setting fonts in a window. 
This file is reproduced in this article to show you some low level 
Toolbox hacking. The file "search.sch" defines a procedure for 
creating a Search menu that is used in this text editor. It's about 
five pages long, and we thought we could safely omit it from this 
article. 
Scheme Syntax 
The syntax for a MacScheme procedure definition is 
(def ine C«procedure-name? «argb...) 
«procedure-body? ) 
where «arg... means zero or more arguments. Most of the 
procedures defined in this program take no arguments. 

Referring to the sample code below, the procedure main 
will be called to begin the application. The call to begin- 
application tells the MacScheme user interface to stop handling 
events. All future events will cause the currently executing 
program to be interrupted while the event is handled by an 
interrupt handler. Interrupt handlers are easy to install and are 
fairly easy to write because they are written in Scheme, but none 
had to be written for this application because the standard 
interrupt handlers provided by MacScheme+Toolsmith were 
sufficient. 

(def ine (main) 

(begin-application) 
(hidewindow 
(Clookup-window-object Cfrontwindow2) 
'windowptr2) 
(pushmenuber ) 
Cinit-search) 
(setup-menus) 
(begin-task ing) 
(start-task idle-loop) 
(start-task relaxation-loop) 
(kill-current-task)) 
The "main" part of our Editor! 

The calls to hidewindow and pushmenubar get rid of the 
MacScheme transcript window and the MacScheme menus so 
the program can replace them with its own menus. The current 
menu information is actually pushed onto a stack and could be 
recalled by calling popmenubar. The call to init-search allows 
the search module to open the resource file containing its dialogs. 
The call to begin-tasking tells MacScheme to generate periodic 
interrupts whether or not an event has occurred. This allows the 
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task scheduler to operate. The program then starts up two 
concurrent tasks, which will run until the user selects Quit from 
the File menu. From this point on the program is driven entirely 
by interrupts while the two tasks run in the background, so the 
initial task can be killed. 

The only thing that the idle-loop task does is to call TEldle 
to blink the insertion point in the front window. The relaxation- 
loop does even less. In fact, the program would run just fine 
without the relaxation-loop task. Its only purpose is to improve 
performance. How can an extra task improve performance? The 
answer has to do with the automatic recovery of storage through 
garbage collection. The idle-loop task allocates a little bit of 
Scheme storage every time it calls TEldle. If it were the only task 
running, it would amount to a tight loop generating garbage. 
Adding a concurrent task makes it call TEldle less often, so it 
generates less garbage and the garbage collector runs less fre- 
quently. 

Our Menu Bar 

The application creates five menus: an apple menu, a File 
menu, an Edit menu, a Font menu, and a Search menu. Each 
menu is set up by a separate procedure. 

Menu objects are created by the make-menu procedure, 
which also installs the menu in the current menu bar. The 
argument to make-menu is a Scheme string giving the name of 
the menu. The most important operation on the menu object 
returned by make-menu is the 'append operation, which adds 
an item to the menu. The 'append operation requires two 
arguments: the name of the item and an action to be performed 
whenever the item is chosen. In setup-file-menu, for example, 
(filemenu 'аррепа "Quit" exit) adds a Quit item to the File menu 
and causes the exit procedure to be called whenever the item is 
chosen. 

The ‘append operation can also take an optional third 
argument: a predicate that determines whether the item should be 
enabled or disabled. Many of the menu items in this application, 
for example, should be enabled only if the front window was 
created by the application. If this optional argument is omitted, 
the item will always be enabled. 

Lambda expressions deserve some mention here because 
they are more general in Scheme than in most other dialects of 
Lisp, and few other languages have anything to resemble them. 
In the expression 

(filemenu 

“append 

"New" 

(lambda С) 

(make-document "Untitled" 8f))) 
the lambda expression evaluates to a procedure of no arguments 
whose body is (make-document "Untitled" 4f). The () is the 
argument list, and the word "lambda" is a syntactic marker 
analogous to "function" in Pascal. When "New" isselected in the 
file menu, this procedure will be executed, creating a new 
untitled document window. This example shows how "object 
oriented" Lisp is, and in fact, it makes a very good introduction 
to object oriented programming. 

One difference between lambda expressions and function 
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declarations in Pascal is that the lambda expression evaluates to 
an anonymous procedure, while Pascal function declarations 
always name the procedure. Another difference is that there are 
no arbitrary restrictions on what can be done with the procedure 
returned by a lambda expression, while in Pascal procedures 
cannot be returned as the result of a procedure call. 

The 'addresources operation on menu objects adds all 
resources of a given type to the menu. Its arguments are similar 
to those for the 'append operation, but the first argument is a 
resource type instead of an item name and its second argument is 
parameterized by an item number. That is, the second argument 
is a procedure that will be called once for each resource of the 
given type. It will be passed the menu item number for a resource 
and must return an action procedure for that menu item. 

Most of the application's behavior is distributed among the 
action procedures for the various menu items. Some calls to low- 
level Toolbox traps can be seen in the action procedures, while 
other calls are hidden inside higher level procedures like stdg- 
etfile, read-file, set-font, and set-fontsize. Calling Toolbox 
traps directly from MacScheme+Toolsmith is a lot like calling 
them from C, and in some ways it is even more difficult in 
MacScheme+Toolsmith than it is in C because C's natural data 
structures are closer to those used by the Toolbox. The advan- 
tages of MacScheme+Toolsmith lie elsewhere. 

One advantage is that the interrupt system and multi-tasking 
makes it easier to separate an application into independent 
modules. Asone trivial example, blinking the insertion point has 
nothing to do with handling events. Another advantage is that 
Scheme is a very good language for building generally useful 
abstractions like window objects, and MacScheme+Toolsmith 
includes source code for several of the most useful abstractions. 

The main abstraction that was developed specially for this 
application was the notion of a document object. Document 
objects correspond to windows created by the application and are 
very similar to window objects, but they must also keep track of 
the name and vrefnum of the file associated with the window. 
This suggests that document objects should inherit the behavior 
of window objects and should be usable in place of window 
objects, just as a WindowPtr can be used in place of a GrafPtr by 
the Toolbox traps. It also suggests that a document object should 
have as its state variables a window object, a name, and a 
vrefnum. It seems convenient also to have document objects 
respond to save and save-as messages. 

The make-document procedure creates a document ob- 
ject. It was written in the same style as the make-menu and 
make-window procedures that are supplied in both source and 
object form as part of MacScheme+Toolsmith. As can be seen 
from the code, a document object is just an ordinary Scheme 
procedure that dispatches on its argument using a case expres- 
sion. If the operation takes no arguments, as in the 'window, 
'name, 'save, and 'save-as operations, then it is performed 
immediately. If the operation takes arguments, as in the 'set- 
name operation, then it returns a procedure that can be called 
with those arguments to perform the operation. The (if args 
(apply (self op) args) ...) nonsense preceding the case expres- 
sionis simply to make it possible to write things like (document 
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‘set-name "Henry") instead of ((document 'set-name) 
"Henry"). 

Since many of the menu actions operate on the front win- 
dow, it must be possible to find a document object beginning with 
the WindowPtr returned by the FrontWindow trap. This is the 
reason for the table of document objects and the lookup-docu- 
ment-object procedure. 

The garbage collector cannot reclaim the space occupied by 
a document object so long as it appears in that table, so document 
objects must be removed from the table when they are closed. 
This is easy to accomplish when a window is closed using the 
Close item in the File menu, but is not so easy to do when the user 
simply clicks in the goaway box of the window. The problem is 
that the standard MacScheme+Toolsmith interrupt handler for 
mousedown events sends the close message directly to the 
window object, bypassing the document object. We could have 
rewritten the interrupt handler or added another interrupt handler 
that deals only with mousedown events in goaway boxes, but we 
instead changed the definition of lookup-window-object, which 
is called by the standard mousedown event handler, to return a 
document object instead of a window object whenever the 
window object is associated with a document. This may be the 
most subtle thing in the program. 

The application as written does not give the user achance to 
save windows as they are being closed. This would be a nice 
feature to add to the 'save operation on documents. There are 
several ways to tell whether the document has been changed 
since it was opened, of which the simplest is to compare the 
window's contents with the contents of the file from which it 
came. 

The value of **task-timeslice** determines the interval 
between task switches. It sets a limit to the rate at which the 
insertion point will blink. 

When a menu item is chosen the associated action proce- 
dure executes uninterruptibly. Ordinary tasks, however, can be 
interrupted at any time. This creates a potential problem. What 
would happen if, after the idle-loop task had fetched the text 
handle for the front window but before it could pass it to TEldle, 
the user closed the window by clicking in the goaway box? The 
system would crash, that's what. The solution is to prohibit 
interrupts between the time that the text handle is fetched and the 
call to TEldle. The call-without-interrupts routine takes a 
procedure of no arguments and calls it uninterruptibly. 

The surrender-timeslice procedure blocks the current task 
until its next turn comes around. Once TEldle has been called, 
there's no point to calling it again a few microseconds later. 

Whenever MacScheme starts up it calls scheme-top-level 
with no arguments. Normally scheme-top-level is the standard 
read/eval/print loop, but for this application we changed it to call 
main. | 

Building Stand-Alone Programs 

Link-application is a simple linker that dumps a 
MacScheme-Toolsmith heap image after stripping unused pro- 
cedures and data. The heap image dumped by the linker is like 
a Smalltalk image file or snapshot. It can be launched by double- 
clicking provided the MacScheme+Toolsmith byte code inter- 
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preter isalso present. An Application Builder is planned that will 
bind heap images together with a stripped down version of the 
byte code interpreter into a single application file, enabling 
standard Macintosh applications to be constructed using 


MacScheme+Toolsmith. 

This code was written by 
Semantic Microsystems, Inc. 
which has placed it in the 
public domain. 


фо Фо Фо Фе 


Pre-release version of the file 
*"texteditor.sch" from 
MacSchene+Toolsmith™ 


Фо Фо wo 


; А simple editing application. 


(begin (set! include-source-code? 8f) 
(set! include-lembda-list? «f)) 


(begin (load ":Chapters:chep20 .data") 
(load ":Chapters:chap20 . traps") 
(load ":Chapters:v2.chap4.data") 
Cload ":Chapters:v2.chap4. traps") 
Cload ":Chapters: chap? . traps") 
(load ":Examples:fs.sch") 
(load ":Examples:files.sch") 
(load ":Examples:fonts.sch") 
(load ":Examples:search.sch") 
(load ":Examples: linker .5сһ" )) 


(def ine (main) 
Cbegin-application) 
Chidewindow 

CClookup-window-object (frontwindow2) 

'windowptr2) 

Cpushmenubar ) 

Cinit-search) 

(setup-menus) 

(begin-tasking) 

(start-task idle-loop) 

Cstart-task relaxation-loop) 

(kill-current-task)) 


(def ine (setup-menus) 
(setup-epple-menu) 
(setup-f ile-menu) 
(setup-edit-menu) 
(setup-font-menu) 
(setup~search-menu )) 


(define (setup-apple-nenu? 
(let (Capp lemenu 
(make-menu 


Clist-»string (list applmark))))) 


Capplemenu 
'eddresources 
(makeZ%restype "DRVR") 
(lambda (n) 
(lambda О 
Clet CCtemp (пенріг 25622) 
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(getitem 

Capplemenu 'menuhandle) 
n 

temp) 

Copendeskacc temp) 
(disposptr temp))))))) 


(def ine (setup-f ile-nenu) 
Clet CCfilemenu Cmake-menu "File"))) 
(filemenu 
‘append 
"New 
(lambda (2 
(make-document "Untitled" #{))) 
(filemenu 
‘append 
"Open..." 
(lambda С) 
(let (Cinfo 
(stdgetfile 68 60 "ТЕХТ"))) 
(let (Cflag Ссаг info)) 
(name Ccadr info)) 
Cvrefnum Ccaddr info))) 
Cif flag 
Clet 
(Cd (make-document 
name 
vrefnum)) 
(contents Cread-file 
name 
vrefnum))) 
Cif contents 
(Cd ‘editor 
'set-textstring) 
(string contents)) 
2222222 
(filemenu 'append 
"Close" 
(lambda () 
(Clookup-document-object 
(FrontWindow2) 
'close)) 
front-window-is-ours?) 
Cfilemenu ‘append 
"Save" 
(lambda С) 
(Clookup-document-object 
CFrontWindow)) 
‘save )) 
front-window-is-ours?) 
(filemenu 'append 
"Save as..." 
(lambda () 
(Clookup-document-object 
(FrontWindow)) 
'Save-as)) 
front-window-is-ours?) 
(filemenu ‘append "Quit" exit))) 


(def ine (setup-edit-nenu) 
(let CCeditmenu Cmake-menu "Edit"22) 
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Ceditmenu ‘append 
"Undo/Z" 
(lambda С) (systemedit 0)) 
, enable only if the 
; front window is not ours 
Clambda (2 
(not 
(front-window-is-ours? ) 
22 
Ceditmenu 'append 


Clambda С) 8t) 
jalways disable 
(lambda С) "f)) 
(editmenu 'append 
"Cut /X" 
Clambda С) 
Csystemedit 2) 
CC lookup-window-object 
Cfrontwindow)) 
‘editor 
"cut))) 
Ceditmenu ‘append 
"Copy/C" 
(lambda С) 
(systemedit 3) 
CClookup-window-object 
(frontwindow)) 
‘editor 
"сору222 
Ceditmenu 'append 
"Paste/V" 
(lambda С) 
(systemedit 4) 
(Clookup-window-object 
(frontwindow)) 
‘editor 
‘paste ))) 
Ceditmenu ‘append 
"Clear" 
Clambda () 
(systemedit 5) 
(Clookup-window-object 
C(frontwindow2) 
‘editor 
‘clear ))))) 


(def ine Csetup-font-menu) 
(let (Cfontmenu Cnake-menu "“Font"))) 
(fontmenu 
‘addresources 
(makeZrestype "FONT") 
Clambda (n) 
(lambda () 
(let CCtempl Cnewptr 2562) 
Ctemp2 Cnewptr 2222 
Cgetitem (fontmenu 'menuhandle) 
n 
temp 1) 
(getfnum tempi temp2) 
(set-font Clookup-window-object 
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Cfrontwindow2) 
(peek.word temp2)) 
(disposptr temp1) 
(disposptr temp2))))) 
Cfontmenu ‘append 


(lambda С) #t) 
(lambda (С) 8f)) 
Cfor-each 
Clambda (size) 
Cfontmenu 'append 
Cnumber->string size) 
(lambda С) 
(set-fontsize 
Clookup-window-object 
Cfrontwindow)) 
size)) 
front-window-is-ours? )) 
"(9 10 12 14 18 24)))) 


(def ine (setup-search-menu) 
(make-search-menu)) 

; Document objects. 

; A document object inherits all the 

; behavior of a window object 

; but it has additional behavior when 

; Sent one of the following messages: 

К window 

Я пате 

; set-name 

j vrefnum 

1 set-vrefnum 


f save 
» save-as 
close 


P 
(def ine (make-document name vrefnum) 
Cletrec 
CCwindow Cmake-window 


‘text 
‘title name 
‘bounds 10 40 500 330)) 
(self 
Clambda Cop . args) 
Cif args 
Capply (self op) args) 
(case op 


CCwindow) window) 
(Cname) name) 
(Cset-name) 
(lambda (newname) 
(set! name newname) 
(let 
CCtemp 
(make%string name))) 
(SetWTitle 
(window 'windowptr) 
temp) 
(disposptr temp)) 
name )) 
(Cvrefnum) vrefnum) 
(Cset-vrefnum) 


(lambda (n) 
(set! vrefnum n) vrefnum)) 
(Csave) 
Cif vrefnum 
(write-file 
name 
vrefnum 
(window 'editor 
'textstring) 
"EDIT" 
"TEXT" 
(self ‘save-as))) 
((save-as) 
Clet CCinfo 
(stdputf ile 60 
60 
name ))) 
Cif (саг info) 
(begin 
(self 'set-name 
(cadr info)) 
(self 'set-vrefnum 
Ccaddr info)) 
(self ‘save))))) 
(Cclose) 
(set! documents 
(remove 
Cassq window 
documents) 
documents )) 
Cif (not (window ‘closed?)) 
(window 'close))) 
(else (window ор2222222 
(set! documents 
Ccons (list window self) 
documents)) 
self )) 


; The global variable documents is 

; an association list with elements of the form 
; («window-object? «document-object? ). 

; Тһеге is ап entry for each window 

; created by this epplication. 


(define documents 'О) 

Given а Toolbox windowptr such as is 
returned by FrontWindow, 
lookup-document-object returns the 
document object associated with 

it or *f if it's not ours. 


we We We We ә = 


; This code also redefines 

; lookup-window-object so that it will 
; return a document object instead of a 
; window object for those windows 

; that have been created by this 

; application. That allows documents 

to intercept a close message sent 

; to a window. 


we 


(define lookup-document-object) 
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Clet CCold-lookup-window-object 
lookup-window-ob ject) ) 
(set! 
lookup-document-object 
(lambda Cwindowptr) 
Clet CCentry 
Cassq 
Cold-lookup-window-ob ject 
windowptr 2 
documents ))) 
Cif entry 
(cadr entry) 
8f )))) 
(set! lookup-window-object 
Clambda (windowptr) 
Cor Clookup-document-object 
windowptr) 
Cold-lookup-window-ob ject 
windowptr)))) 
8t) 


(def ine Cfront-window-is-ours?) 
Clookup-document-object (frontwindow))) 


; Concurrent tasks. 


(def ine **task-timeslice** 500) 


; This procedure soaks up idle time 
; with occasional calls to TEIdle. 


(define Cidle-loop) 
(call-without-interrupts 


Clambda О 
Clet CCtexth. CClookup-window-object 
(FrontWindow)) 
‘editor 
‘tex thandle))) 


Cif texth Cteidle texth))))) 
Csurrender-times] ice) 
Cidle-loop)) 


; Running this procedure as a concurrent 

; task improves interactive performance 

; because 

; (1) this procedure creates no garbage 
whatsoever (so running it as a 
task makes garbage collections 
occur less frequently); 

(2) all pending interrupts are 


Н accepted each time through the 
; loop (because the time procedure 
s enables interrupts). 


(def ine Crelaxation-loop) 

(time) 

(relaxation-100p)) 
; The scheme-top-level procedure is 
; called when MacScheme starts up. 


(def ine (scheme-top- level) 
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; exit if an error causes а reset 
(set! scheme-top-level exit) 
(main) 
Cexit)) 

Clink=-application) 


This code was written by 

Semantic Microsystems, Inc. 

which has placed it in the 

public domain. 

Pre-release version of the file 
"fonts.sch" from 

MacSchene*Too1snith" 

Simple font hacking. 

The pre-release version of this code has 
some bugs that will be fixed in the released 
version of MacScheme*Toolsmith. When a font 
is not available in the specified size, 

the presentation on the screen can become 
garbled. 

Suppose w is а text edit window created by 
the Toolsmith, f is a font number of a font 
(see chap7.data), and n is a font size. 
Then: 
; Cset-font w f) will change the window 

to use font f 

; (set-fontsize wn) will change the window 


"Ww" Фо Be Фе Фо He Be Фо 


Bee Be We We We We We 


" We We We We 


j to use font size n 
; Example: 

К Clet (Cw Cmake-window 'text2)) 

; (set-font w monaco) 

: (set-fontsize w 9)) 


; If this code doesn't work for you, 
; check to make sure that the font you want, 
; in the size you want, has been installed 
; in the System file you are using. 
(def ine chicago 0) 
(def ine geneva 3) 
(def ine monaco 4) 
(nac-type FontInfo 
(record 
Cascent integer) 
(descent integer) 
(widMax integer) 
(leading integer 222 


(define textfont Cmake-trap "a887" 1)) 
(define textsize (make-trap "ә88а" 1)) 
(define getfontinfo (nake-trep "a88b" 12) 
(def ine Cset-font w font) 
Ccall-without-interrupts 
(lambda () 
Cif (not Cw 'closed?)) 
Clet CCtexth. (Cw 'editor) 
‘tex thandle))) 
Cif 
texth 
Clet (Ca Cw ‘editor ‘selstart)) 
(b (w ‘editor ‘selend))) 
(роке .handle.word 
tex th 
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(Soffset TERec txFont) 
font) 
(Cw ‘editor 'set-textstring) 
(w ‘editor ‘textstring)) 
(w ‘editor 'set-selection a b) 
(w 'editor 

'scroller 

‘show 

(w 'editor) 

а)))))))) 


(define Cset-fontsize w n) 
(call-without-interrupts 
Clambda О 
Cif (not Си 'closed?)) 
(let CCinfo Cnewptr 
(Zsizeof FontInfo))) 
Ctexth (Cw 'editor) 
‘texthandle)) 
(а (w ‘editor ‘selstart)) 
(b Cw ‘editor ‘selend))) 
Cif texth 
(begin 
(роке handle .word 
texth 
(Zoffset TERec txSize) 
n) 
(SetPort (w 'windowptr)) 
Ctextfont 
(peek . handle .word 
texth 
(Zoffset TERec txFont))) 
(textsize n) 
(GetFontInfo info) 
Cpoke.handle.word 
tex th 
(Soffset TERec lineHeight) 
(+ 
(peek .ptr . word 
info 
(Sof fset FontInfo ascent2) 
(peek .ptr .word 
info 
(Zoffset FontInfo descent)) 
(peek .ptr .word 
info 
(Zoffset FontInfo leading) 
22) 
(роке handle . мога 
texth 
(Soffset TERec fontAscent) 
(peek .ptr .word 
info 
(Soffset FontInfo ascent))) 
(Cw ‘editor 'set-textstring) 
(и ‘editor ‘textstring)) 
(w ‘editor 'set-selection a b) 
Cw ‘editor 
‘scroller 
‘show Си 'editor) a))) 
(disposptr info)))))) 


The Visiting Developer 


Multitasking in MacScheme+Toolsmith™ 


Thanks to MultiFinder, every- 
one knows that multitasking lets 
yourun more than one thing at once. 
In an operating system like Multi- 
Finder, multitasking means that you 
canrun more than one application at 
once. In a programming language, 
multitasking means that you can run 
several parts of your program at 
once. This article explains why you 
might want to use multitasking 
within a single program, and warns 
against a class of bugs that you must 
guard against when you do use 
multitasking. It also surveys the 
multitasking facilities іп 
MacScheme+Toolsmith™ , which 
are probably the best developed of 
any language for the Macintosh. 

The Macintosh contains only one 68000 or 68020, but there 
will come a day when most computers contain many such 
processors. Then multitasking will make programs run faster 
because the processors will work as a team, with each processor 
working on its part of the problem to be solved. These pieces of 
a problem are of course called tasks. 

A single hardware processor can work on only one task at a 
time. To get the effect of working on multiple tasks at once, the 
processor must switch between tasks. In MultiFinder, these 
switches occur only when a task calls GetNextEvent or WaitNex- 
tEvent. If a task were to get into an infinite loop where it never 
calls one of these routines, that would be the end of the multi- 
tasking. This is what people mean when they say that MultiFin- 
der does non-preemptive multitasking. It never interrupts, or 
preempts, a running task. Task switches can occur only when a 
task yields control by calling GetNextEvent or WaitNextEvent. 
Applications are supposed to call these traps fairly often, so 
MultiFinder works well in practice. 

MacScheme+Toolsmith, on the other hand, does preemp- 
tive multitasking. MacScheme programs do not have to call 
GetNextEvent or WaitNextEvent, because there is a separate 
task that calls these traps. Every so often, 
MacScheme+Toolsmith simply interrupts the currently execut- 
ing task and switches to a new task. Preemptive multitasking is 
more reliable than non-preemptive multitasking because it works 
even when a buggy task gets into an infinite loop. This kind of 
reliability isn't very important for an operating system like 
MultiFinder because applications aren't supposed to be buggy, 


(define Cunequal2 x . 
Clet* (Cans 8f) 
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% File Edit Command 


CCnull? lists? 9f) 

(Cequal? x (саг lists?) 
Capply unequal! (cons x Cedr 
Celse (сағ lists)))) 


lists) 


li«t«55)5 


William Clinger 
Tektronix Laboratories 
MacTutor Vol. 3 No. 12 


A 


TxScheme 


transcript 
>>> (load "timeit.sch" > 
timeit 
et 
>>> (define (foo? 
(vector-»list (make-uvector 10000 'а))› 

foo 
>>» (begin (set! х0 (foo?) 

(set! x1 (Тоо?) 

(set! x2 Cfoo?) 

(set! x3 (foo?) 

(set! x4 (foo?) 

(set! х5 (Тоо?) 

(set! x6 Cfoo?) 

et) 


(task-count (length lists?» | St 

(tasks (map Clambda (Cy) 
(start-task 
Clambda (2 


>>> (timeit Cunequali х0 x1 x2 x3 "а x4 x5 хб?) 


Timings for Cunequali х0 x1 x2 x3 "а x4 x5 хб) 
total time (msec): 3967 
gc time (msec): 
collections: 
bytes allocated: 


a 
>>> Ctimeit Cunequal2 х0 хі x2 x3 ‘a x4 


but it matters a lot for a development system like 
MacScheme+Toolsmith because all programs are buggy when 
you're trying to debug them. 

Why wouldanyone wantto use multiple tasks within a single 
program? Why not perform the tasks sequentially—that is, one 
after the other? А good question. It turns out that multple 
concurrent tasks within a single program are much more useful 
on the Macintosh than on most other computers. Consider, for 
example, the task of blinking the insertion point within a text 
window. That task lasts as long as the window is open. Youcan't 
run tasks like that in sequence, because once you've started such 
a task you'd never get to any other tasks. 

Does this seem artificial? How about the task that changes 
the cursor's shape in response to its position on the screen? How 
about the task that updates the time displayed on the alarm clock? 
A considerable part of the Macintosh user interface really con- 
sists of concurrent tasks. Because the original concept of the 
Macintosh did not include real concurrent tasks, however, these 
features of the user interface have generally been programmed 
using such clumsy mechanisms as event loops and desk accesso- 
ries. 

An alternative is to use the vertical retrace manager to 
perform preemptive task scheduling. The operating system task 
that performs mouse tracking is one of the tasks that is pro- 
grammed this way. The vertical retrace manager is not generally 
useful, though, because tasks that run during a vertical retrace 
interrupt are very restricted in what they can do and must yield 
control of the processor within a very short time. 

The most general alternative is to use a language that 
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supports concurrent tasks. User interface chores are routinely 
implemented as concurrent tasks by programmers using 
MacScheme+Toolsmith. To create a task in 
MacScheme+Toolsmith, you first create a procedure of no argu- 
ments that will perform the task. Then you pass that procedure 
as an argument to start-task. For example, you can define a task 
that perpetually increments a global variable n as follows: 


>>) (define n 0) 
n 
››› (define Cloop1) 
(set! п C+ n 120) 
(100p 122 
loop 1 
››› (define ti Cstart-task 100р1)) 
t1 


The call to start-task begins the concurrent task. You can 
Observe its progress by checking on the value of n. 


››› п 
46954 
››› п 


103925 
››› п 
165850 
››› п 
184428 


The value returned by start-task is a task object. You сап kill 
the task by calling kill-task. 


››› n 
7 18335 
››› п 


128243 
››› (kill-task t1) 


Ifthe procedure that was passed to start-task everreturns, the 
task will kill itself automatically. A task can kill itself explicitly 
by calling the kill-current-task procedure. If all tasks die, then a 
warning message will appear and a new task will be created for 
the read/eval/print loop. The kill-all-tasks procedure will track 
down and kill all tasks, including runaways, which is useful for 
debugging. 

If an error occurs, task switches are disabled while you 
investigate the problem using the MacScheme debugger. This 
keeps variables from changing on you until you've figured out 
what's going on. Tasking resumes when you've repaired the 
problem and continue the computation from the debugger. 

You can improve the overall performance of a program by 
having your tasks call surrender-timeslice to force an immediate 
task switch whenever they don't need to run again for a while. 
For example, a task that is blinking the insertion point in a 
window can afford to wait for a substantial fraction of a second 
before it blinks again. The surrender-timeslice procedure is 
analogous to the WaitNextEvent trap, which improves the task- 
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ing performance of MultiFinder when applications call it in 
preference to GetNextEvent. | 

Because it takes time to switch between tasks, you might 
think that on a single processor system such as the Macintosh 
programs that don't use concurrent tasks would run faster than 
otherwise equivalent programs that are organized as concurrent 
tasks. That's usually true, but not always. Figure 1 shows a 
procedure that takes a pattern x and arbitrarily many additional 
arguments, and tries to find one of them that is not equal to the 
pattern. If the program is such that most of the arguments are 
equal to the pattern, and the arguments are large structures (so it 
takes a long time to compare them against the pattern if they are 
equal), but there is usually one argument that is so different that 
it can quickly be determined to be unequal once the procedure 
gets around to trying it, then the procedure in Figure 2 will run 
fasteron the average. Thereasonisthatitconducts a breadth-first 
search using concurrent tasks instead of a sequential, depth-first 
search. 

A breadth-first search could be programmed explicitly with- 
out using tasks, but that would make it much more complicated, 
and the resulting procedure might well run slower than the 
procedure in Figure 2 because the programmer would probably 
not be able to spend as much time optimizing the breadth-first 
search as was spent on the multitasking facilities of 
MacScheme+Toolsmith. 

The procedure in Figure 2 works by creating a task for each 
argument except the first. Whenever a task finds that its argu- 
ment is not equal to the pattern, then it stores its argument ina 
variable named ans. Meanwhile the procedure that created these 
tasks just waits for one of them to find the answer or forall of them 
to finish. How does it know when all of the tasks have finished? 
The task-count variable holds the number of tasks that have not 
yet finished. When it gets to zero, then either all the tasks have 
finished, or else one of the tasks has found an answer and has set 
the task-count to zero to indicate that the remaining tasks are 
irrelevant. When the task-count gets to zero, the main procedure 
kills all the tasks it has created, just in case some of them are still 
alive (it doesn’t hurt to kill a task twice), and returns the answer. 

Actually, there is a very interesting bug in Figure 2. It has 
to do with the assignment 


(set! task-count (- task-count 1)) 


that is executed whenever a task has found that its argument 
is equal to the pattern. Suppose two concurrent tasks, t1 and t2, 
try to execute this assignment at the same time. Suppose further 
that the value of task-count is 2, so that task-count should be 0 
after both t1 and 12 have executed the assignment. If we're 
extremely unlucky, then t1 might fetch the value of task-count, 
andthen t2 might also fetch the value of task-count while t1 is still 
subtracting 1 from 2. Thent1 would store a 1 back in the variable, 
and so would t2. The variable would never reach zero, so the 
procedure would never return. 

How do we fix this bug? The assignment must be executed 
as an uninterruptible atomic action, so that only one task at a time 
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can execute any part of it. To accomplish this, 
MacScheme+Toolsmith supplies a procedure named call-with- 
out-interrupts that takes a procedure of no arguments and calls it 
uninterruptibly. We can therefore fix the bug by changing the 
assignment to 


(call-without-interrupts 
(lambda С) 
(set! task-count (- task-count 1)))) 


This bugis typical of a new class of bugs that you must watch 
out for when using multitasking. At the operating system level, 
file i/o is the analog of assignment. Developers need to watch out 
for this class of bugs, which may show up whenever an applica- 
tion writes to a file that another application might read. 

The worst thing about this kind of bug is that it never seems 
to show up when you test your program. It only shows up when 
your customers use it. The only way I know to avoid making 
mistakes like this is to gain lots of experience with multitasking, 
and to be fanatically careful about assignments, file i/o, and all 
other side effects (changes to shared state). Because this whole 
class of bugs is caused by side effects, many researchers believe 
that languages without side effects, such as pure Lisp, and 
languages like Scheme that encourage programmers to develop 
a style that uses relatively few side effects, will be the most 
practical languages for programming the powerful multiproces- 
sor systems that are expected in the future. 


MacScheme is a registered trademark of Semantic Mi- 
crosystems, Inc. MacScheme+Toolsmith is a trademark of 
Semantic Microsystems, Inc. 


Figure 1. 


(def ine Cunequali x . lists) 
(сопа CCnull? lists) 8f) 
CCequal? x (саг lists)) 
Cepply unequall (cons x (cdr lists)))) 
(else (саг lists)))) 


Figure 2. 
(begin-task ing) 


(define Cunequal2 x 
(let* (Cons tf) 
Ctask-count (length objects?) 
(tasks (map (lambda (y) 
(start-task 
Clambda () 
Cif (not Cequal? x y)) 
(begin (set! ans y) 
(set! task-count 0))) 
(set! task-count (- task-count 122222 
objects))) 
(while (> task-count 0) 
Csurrender-timeslice)) 
Cfor-each kill-task tasks) 


. objects) 


ом 


ce 
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The Mousehole Report 
Ghost Windows & Disk Timing 


The One and Only Original Mousehole! 


Vol. 3. No. І 


Great Disk Timer Shoot-out! 

We've been having a bit of a challenge here lately. Which 
hard drive is the fastest? Which is the best? What are our 
conclusions? You won't want to know, maybe. The fastest drives 
were the HD-20SC, The Dataframe XP and the ProAPP 20 and 
40S, not in that order. Drives with the fastest read/write time 
didn't necessarily have the fastest access time. Internal RAM 
caching (e.g. the ProAPP) helped some tremendously. And our 
results didn't take boot speed into account. Dataframes seem to 
take forever to boot, HD-20s (the non-SCSI ones) seemed to be 
much faster. 

We're dropping speculation about the "January" Mac (Al- 
ladin some call it) because it will probably be announced by the 
time you read this. [Haha ha! Where have I heard that one before? 
-Ed] The Milwaukee is a different story, pre-release developer 
machines are starting to pop out of the woodwork as we speak; 
which means that everyone who has them is under piles of non- 
disclosure statements. So we can't tell you that it has multiple 
slots, an eighty megabyte internal hard disk, slots, floating point 
co-processor standard, slots, multiple video options (big mono, 
bigger mono and big color), 2mb of memory-managed RAM 
initially (eventually expandable to a gigabyte), slots, 14-16mHz 
processor speed, and of course, slots. We'll see. [Who needs 
slots? -Ed] 

Can't find a SASE to send to us? For the month of January 
we are offering a trial online sign-up. Here's how it goes. Call 
(714) 921-2252. When you get the Login promp, type MACTU- 
TOR GUEST. This will prompt you for a stream on information 
and then you will have your very own MouseHole acount. Sound 
exciting? Think of it as a sort of a late Christmas present! 

Finally, we hope to see you all at the San Fransisco 
MacExpo. Look for us and we'll look for you. - Rusty 

68030 
Frank Henriquez 

With all this hype in the press lately over the 80386, most (if 
notall) have overlooked the simple fact that a 68020 will be faster 
than the 80386...the 68020 has an internal cache. The 80386 does 
not. Unless the 80386 has a lot of fast static ram to play with, it's 
going to have to insert a wait state or two (just like most 68020 
systems) BUT, with the cache bit enabled, the 68020 will not 
have to access external memory as often, and will therefore run 
at full speed. I've seen benchmarks where the 68020 (0 16 MHZ 
is 20-3096 faster than the 16MHZ 80386. 

The 68030 is another story; apparently Motorola has in- 
cluded some fancy memory interleaving hardware AND separate 
data and instruction caches. I've heard that a properly designed 
'030 system could run with only occasional wait-states, at 
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Rusty Hodge 


Contributing Editor 
Mousehole BBS Sys Op 
PO Box 2323 


Orange, CA 92669 


25MHZ+, using standard DRAMSs. Now, that is quite a feat. And 
since the '030 is basically a 68020 deep down inside, it should be 
fully compatible with the 68000, 68020 etc. 
80386 
James B. Du Waldt 

I was under the impression that the '386 did have an 
instruction cache, like the '020, but maybe I'm wrong... One of the 
real problems with the new, very fast processors is, as Frank 
mentions, RAM speed. We're going to seealotofhigh speed, low 
end stuff having to use static row and/or nibble addressing in 
order to keep up with the 16 MHz '386, not to mention the 20 and 
25 Mhz '0205... 

A brief note on workstation sales... Sun 20,000 units/yr (all 
figures approx.); Apollo 20,000 units/yr; DEC 12,000 units/yr; 
IBM 6,000 units/yr. 

Industry editors/writers are beginning to think that the RT 
(apparently gives a new meaning to "Reduced" instruction set 
computers...) just ain't gonna make it, several months after saying 
how slowly windows close on IBM... (I agreed with them, still 
do, but I was HOPING it would...) 

Some of the companies that announced early support of the 
RT are now dropping their porting plans. I guess selling to people 
(ie, engineers) who aren't afraid of technology isn't quite as easy 
as selling to MIS folks... After a year, complaints are still the 
same, bad graphics & no networking. 

Resources 
Mike Steiner 

Why has so much attention been given to how to write a 
resource and then compile it with RMaker? Why not just write 
your code and your unique resources and then use Resedit to 
write your window, menu, dialog, etc. resources? (or write the 
resources first and then the program). I'd think that putting 
resources together with Resedit would be easier than having to 
write the code from scratch without the visual interface that 
Resedit affords. Maybe this might make an interesting ‘Tutor 
article for someone to write. [The problem is, how do you publish 
a resource file made with ResEdit? You can't. So a lot of the 
usefulness is lost if you can't convey the idea to someone. In this 
respect, MPW has it all over MDS because MPW has a resource 
compiler and de-compiler that are compatible and opposite in 
function. -Ed.] 

ResEdit vs. RMaker 
Jim Reekes 

I agree with you Mike. I've never used RMaker, because 
most the the resources are graphic items and R Maker is a text- 
based tool. I have forever, and will always use ResEdit to create 
my resources. I've made just about every type of resource totally 
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using ResEdit before writing ANY code. I have a library of 
generic resource items that I start with. Then with little modifi- 
cation I customize them for my new program. Then after all my 
resources are completed, which also allows me to play with the 
user interface, I'll start writing code LAST. I find this method 
greatly helps me to build programs quickly and easily. 

I think the RMaker utility is just a cheap way to publish a 
resource in print. Until magazines start getting published on disk, 
how else can someone document a resource? I'd like to write or 
help someone write an article on using ResEdit instead of 
RMaker. 

New HFS?!?! 
Micro Man 

From what I understand, Apple is rewriting HFS forthe new 
slotted Mac due out first quarter. Last prototype unit that landed 
in this area came with 2000+ pages of appendums to the docu- 
mentation of why your code doesn't work now. When our "guru" 
friend asked Apple about compatibility, all they would say is, 
"well it started out compatible" Has anyone else had similar 
dealings yet? I personally am not really in the mood to start over 
again come February re-writing code to fit the "NEW STAN- 
DARD". [Amen. -Ed] 

Also, Apple's Sales Reps are starting to get a little loose 
tongued lately. Look for one Mac in January, another in May. 
Last I heard, Apple is suggesting dealers clear LOTS of floor 
space for Apple products starting in the April - May time frame. 
Look to see MUCHO monitors in all shapes, sizes, and colors. 

Tops vs Macserve 
MacoWaco 

In Nov's Mactutor I'm quoted from the MH regarding 
Macserve. An editors comment endorsed Tops within my quote. 
I would like to rebutt the editors' comment along with a bunch of 
other pro Tops comments. I've learned from northern sources that 
Centram's Tops does not use Apple's File structure, while 
Macserve does. While this might not seem to matter all that much 
to the operator at this time... it willlater. [If someone out there can 
give us the precise technical scoop on exactly how Tops and 
MacServe work, we would love to publish it and clear up the 
confusion between these two products. -Ed] 

Word 3.0 
Rick Boarman 

I talked to Microsoft today and they said Word 3.0 will be 
released sometime in Jan. The cost for people who bought 1.05 
before 10-1-86 will be $99.00, $50.00 for people after 10-1. 
Sounds pretty steep to me. Is it worth it? 

Tim Celeski 

At $50-99 for an upgrade, Word 3.0 is an absolute steal. It's 
hard not to be so enthusiastic, since I've been working in it for 3 
months. I suggest as Microsoft starts making the User group 
circuit that people attend a demonstration. Dealers will not have 
a demo until the product is released in January. It's great! 

Mac Fortran Interface 
Blacksmith 

More information on McFace for you Fortran program- 
mers: "McFace is a Fortran-callable unlinked external subrou- 
tine which creates a Macintosh user interface for existing Fortran 
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programs. McFace adds access to desk accessories, file han- 
dling, text editors, picture editing, alerts, and dialogs without a 
single call to the toolbox by the main Fortran program..." The 
author can be reached by phone at (217) 328-5842. [Watch for an 
article on this product in MacTutor.-Ed] 
Interesting experiment 
Mike Steiner 

Try the following: Take an HFS disk that has some files in 
the disk window. Check the memory available on the disk. 
Create a new folder and put some files into it. Now look at how 
much memory is available. Now try to get the lost memory back. 
You can take the files out of the folder, trash the folder, rebuild 
the desktop, etc. to no avail. The only way I have found to do it 
is to copy the disk to another disk. It seems that a folder takes up 
disk space that cannot be recovered. I'm using system 3.2 and 
Finder 5.3 for this. 

Excel upgrade 
Macowaco 

ILOVE the hint in the letter I got for the EXCEL upgrade. 

Version 1.03 will take advantage of the 68881 coprocessor. 
Remove Macsbug, why? 
Jim Reekes 

[In response to "How can you detect Macsbug is loaded in 
your Mac"] 

Let me guess what you're trying to do. Remove Macsbug to 
keep someone from unprotecting your program. Without getting 
on a soapbox and pleading "no copy protection please", ГЇЇ 
explain why removing Macsbug would be a bad idea. 

Macsbug gets installed during system load time below the 
Main Screen Buffer ($7A700). Then the sound buffers, jump 
tables, application parameters, application globals, quickdraw 
globals, and finally the CurStackBase get installed below this. 
All of these addresses will change depending on the version of 
Macsbug in use. All of this will happen before any of your code 
is excecuted. You could not remove Macsbug and reload all of 
these addresses. Therefore, you would have erase a section of 
high memory and leave the area blank. 

BASIC 3.0 Features 
Gary Voth 

According to Microsoft, the MS BASIC 3.0 Interpreter has 
the following enhancements: 

* Toolbox Support. In the new version, you'll be able to 
directly use resources, add command-key equivalents to menus, 
and make toolbox calls, etc. Microsoft basically purchased the 
marketing rights to the Clear Lake Research toolbox assembly 
language libraries and grafted them in to the interpreter, calling 
them the "Microsoft Basic Toolbox Library". At least, you can do 
as much as you could under MS Basic with the CLR libraries. So, 
at best, this will be a superficial interface Toolbox. No low level 
File Manager calls here! 

* Runtime Package. Microsoft has finally understood that 
waves of commercial Macintosh developers are NOT rushing out 
to license their MS BASIC runtime package at almost $300 per 
year, so they are now going to include it with the interpreter. Last 
I heard, though, the runtime was a separate file, and could not be 
"bundled" with a BASIC application to produce a single, double- 
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clickable program. [Not true. You can link the runtime library 
into a stand-alone program without paying fees. -Ed] 

* HFS Compatibility. Yes, there are new enhancements to 
the FILES functions that return directory information to your 
program. There is also a way of changing the "default" directory 
on the fly. 

е Multi-line IF... THEN..ELSE Constructs. New to this 
level are block IF/THEN/ELSE statements that permit a more 
structured coding style. 

* А Miscellany of Other Stuff. Like SADD, for String 
Address function, whichallows you to pass the address of a string 
variable to a machine language subroutine. 

That's all I know at this time. Мо word on price or 
availability. I wastold that the compileris "under development," 
which I know is a stunning surprise to all of you. [Microsoft has 
begun a direct mail marketing program selling Basic for $99 if 
you order direct by Jan 15th. Call (206) 882-8088 for more info. 
-Ed] 

Dave Kelly 

Yes, I too have recieved my update notice. $25 to upgrade, 
but this gives you 140 CLR Libraries routines and multiline IF- 
THEN ELSE ENDIF type statement. Better support for Laser- 
Writer. Fixed HFS problems and added CHDIR to change the 
directory. The compiler apparently has not been finished quite 
yet even though I think they wanted to have both done at the same 
time. It will probably (my guess only) be a new product which 
you'll have to pay extra for. 

As the ad in MacWorld says, the compiler will support all 
the new 3.0 stuff. By the way, about a month ago someone from 
Microsoft called me and asked me what I thought they should do 
toimprove MS Basic. I think they took some of my ideas, but not 
all. They had been reading the "BASIC WARS" Mactutor 
column where I reviewed ZBasic and others. I think they were 
finally seeing that they had to act fast to just keep up and work 
even harder if they wanted to keep any advantages over ZBasic. 
ZBasic is a much better product now. Version 3.02 is out and 
most bugs are gone. I'm almost ready to recommend it to 
everyone, but they are re-writting their editor and I'll wait till it 
comes out. By then maybe MS will have their compiler out too. 

Hard Disk Survey 
Bugs 

Here are my times for DiskTimer 1.1 and my 1OMB Hyper- 
Drive. I have the OLD 128K motherboard and the OLD Hyper 
controller board (rev 1.0). I am, however, running HFS with the 
new 128K ROMs and General's V3R1 software:100 32K reads, 
133.0; 100 32K writes, 114.5; 80 seeks across 1MB, 6.7 

Hobbit 

My Hyperdrive 20 running on approximately a 512E (it has 
been upgraded so many times I don't know what it is!) gives the 
following times: 100 Reads 26.5 sec, 100 Writes 25.0 sec, 
Access time 2.8 sec. 

Ok, so now I've got version II. Here are the results with my 
512Е and Hyper 20 running V3R1 (the latest & ...... ): 


Test w/o caching w/ caching 
100 24k reads 188 ds 184 ds 
100 24k writes 187 ds 187 ds 
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80 seeks across 1MB 30 0 
ProAPP 40 
The Anarchist 

I just got my new ProAPP 40mb hard disk. This drive is 
REALLY nice. It uses a 3.5" 2 platter disk mech, with built in 
SCSI controller. The typical read/seek time is 28-29ms. I have 
used a lot of SCSI drives but this is DEFINITLEY my favorite 
now! I have about 27 out of 40 megs full, and have had NO 
noticible speed decrease, either reading or writing. 

If youare looking for a new disk, this is the one. The 40meg 
version retails for $1995, and the 20meg version for $995. These 
prices INCLUDE all applicable sales tax and shipping charges! 
[Note: There is developer pricing for real developers, according 
to ProAPP] 

ProAPP 40s: 21.7 read; 21.2 write; 3.1 across 1mb. 

Jim Reekes 

Here's my results of bench marking the ProAPP 40. The 
drive had nearly 35mb of data. I've tested a freashly formatted 40 
with less than 1mb, but the results were the same. 

DiskTimer test: READ = 21.4; WRITE = 21.2; ACCESS 
TIME = 2.2. 

Jcom 

Timing results from Disk Timer II For HD-20: 874,294,37. 

For ST-225N (as used by Loy Spurlock): 194, 294, 37. 
Dataframe 40XP 
Tj 

I just ran Disk Timer on Scott Winders' 40Mg XP and it 
screams!!!!. Here are the results: 

Reads 6.9, Write 7.6, Access 1.8. 

Scott Winders 

Just got my Dataframe 40xp today and was blown away the 
Disktimer 2 results: 

Reads 53, Write 55, Seeks 18. That is the fastest drive I 
have seen yet!!! 

Disk Timer 11 
Dave Morris 

Results from DataFrame20 (original) w/Mac+: Reads 146, 
Writes 146, Seeks 68 

Note: This is with INIT 1.5 software. INIT 2.1 would blow 
up on me after loading the disk with System/Finder. 

Micah AT20 
The Psuedohacker 

Here's the averaged results of three tests on my Micah 
AT20, (a drive whose company is having financial problems). 

Reads: 5: Writes: 59 Seeks: 72 

Personally, I like the drive. It's the company that's got me 
worried. 

Relax Technology 
Ross Yahnke 

I'm the proud owner of a Relax Technology Hard 20 Plus 
disk drive. I guess it's got a Seagate drive in it. I'm real happy 
with it ‘cept it has a noisy fan. Anyway, my disktimer II 
results are: 

100 24KB reads: 194 

100 24KB writes: 293 

80 seeks: 37 
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The disk cache was off when I ran this. 
Noisy Fans 
The Anarchist 
That is probably the hard disk, not your fan that is noisy. I 
had an SCSI drive that had the ST-225N in it, and it made more 
noise than the boxer fan... 
DiskTimer 
Max 
More results for the Great Disk Timer Shootout: 
For an EasyDrive 30-meg SCSI drive (based on a Seagate 
drive): 
100 24KB Reads: 422 
100 24KB Writes: 425 
Access Time: 36 
For what it'S worth, I've had personal experience with 5 
(yup: 5 different ones) of these drives, and I've found them to be 
tireless: 3 of them are on all day long... and have been for about 
4 months. They're cheap. They don't break. The manufacturer 
is in the City of Orange [CA, Home of MouseHole!). They have 
а 1 year warranty. 
GhostWindow? 
The Corsair 
What I want to do is a tool window almost exactly like the 
one in Fullpaint that will stay in front of all the other windows no 
matter what. I would like to pass events to it using DialogSelect 
like all my other dialogs 
Here is a quote from inside mac - "In the global variable 
GhostWindow, you can store a pointer to a window that's not to 
be considered frontmost even if it is (for example, if you want to 
have a special editing window always present and floating above 
all the others). 
This is what I want, So I do a GhostWindow = 


(WindowPtr)GetNewDialog(... 

and what I get is a window thatis just the opposite from what 
inside mac says... 

The reason I want this is because normally everytime this 
window gets covered I have to do a BringToFront and that looks 
lame... 

GhostWindow 
Chief Wizard 

The function of GhostWindow is not to keep a window in 
front of all other windows, but rather to pretend it isn't when it 
really is. 

What I mean is, if you have a window and you store its 
pointer in GhostWindow, any calls to FrontWindow will not 
retum your ghost window even if it really is in front. This way, 
you can have it highlighted at the same time as another window 
and have the next-to-front window be the "Active" one that gets 
all the normal events because it gets returned as the result of 
FrontWindow. 

Unfortunately, you have to handle the GhostWindow 
completely manually. Because the window will get unhigh- 
lighted and moved to back if you activate another window, you 
have to constantly bring yours to the front. But that causes all 
sorts of flicker and other problems because of some of the things 
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the ROM is doing. 

We use a GhostWindow palette in dBASE Mac, and we 
wound up writing our own versions of some of the Window 
Manager routines to avoid having our palette flicker all the time. 

DLOG defaults 
Mark Chally 

Im having a hard time figuring out how to highlight the 
default button in a dialog. According to a couple things I read, 
it seems it's supposed to be "automatic" if you have a button that's 
item number one. However, it didn't seem to work for me. 
Anyone have the solution? 

Sam 

The default is automatic if you use ModalDialog. It will 
return a 1 in itemHit if the return or Enter key is hit. If you don't 
use ModalDialog you're supposed to support the return/enter = 
OK anyway (Macintosh user interface guidelines -- hee hee) 

To automatically draw a box around the item, its not 
automatic... you have to do the drawing. 

Do a GetDItem(OK button) and use the rect it returns in 
"theBox": 

PenSize(3,3); 
InsetRect(theBox,-4,-4); 
FrameRoundRect(theBox,16,16); 
'Automatic' Highlight 
Chief Wizard 

The automatic highlight does actually exist. Only it's for 
Alert calls, not dialogs. 
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Be Bl 

We're taking bets: What is Apple going to introduce at the 
MacWorld Expo in San Fransisco? Some people think Apple 
will introduce the next progression of the MacPlus. Some people 
think Apple will wait. IBM has boughta bunch of time during the 
Super Bowl, so Apple may not have a terrific advertisement 
waiting for us. Oh well, the world will be in better focus after the 
Expo. 

ShareWare — it works!!! 

From: Go 

Well, whaddya know? The shareware system of software 
distribution actually works! A mere 13 months after I finished 
the first version of my program (the FONT-FKEY DA Sampler), 
I finally received a check for $10 from a satisfied user! It's good 
to know that there are people out there in MacLand who appre- 
ciate the value of good programs, and make us programmers 
actually feel good about writing them. Thanks people, your 
contributions will certainly go to a good cause (like renewing my 
MacTutor subscription!). [This guy could use some money! How 
about sending in those shareware fees folks? -Ed] 

Job Security 

From: Macowaco 

A way to keep your job no matter what....write in Forth. 
Pro3D is all in Forth... AND ONLY ONE GUY KNOWS THE 
CODE! Something to consider when thinking about which 3D 
drawing app to go with. [I used to write PDP-8 asm test programs 
at Hughes for the same reason! -Ed] 
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Microphone Patch 

From: Katz 

I came up with a patch for Microphone to skip the opening 
dialog box. 

Search for:4EAD 0582 
Replace:600A 0582 

FEdit on big disks 

From: Bob Denny 

For those interested, I had FEdit 1.0.1 using it on the 
PROApp 40MB disk I'm testing. It acted pretty funny, with 
"Unknown node type in catalog..." alerts, etc. I had just done 
something I wasn't confident in anyway, so I went to reconstruct 
the disk. Turned out to be FEdit. Get the later version (1.0.7). 
The bug is fixed since version 1.05. PS: The bug seems only to 
show on 40MB disks, not 20MB, etc. [Note: MacTutor is now 
shipping 1.07 of FEdit, which is the latest as of 1/5/87. The bug 
affects only drives over 32MB. A new version 2.0 is due to ship 
sometime in February. Registered owners will receive update 
information in the mail. -Ed] 

EXCEL bug 

From: Macowaco 

We got a bug in 1.03. When trying to cut and paste between 
two linked worksheets up came the bomb. It was very replicable 
but also due to the contents of the worksheets. 

[Then there is the bug that makes the row labels dissappear, 
and re-calc bug, and so on... A lot of people think the original 
version is less buggy! Just watch out for the exploding print 
command when using old MFS-saved documents. - Rusty] 

Backing Up with MacBack 

From: Rick Boarman 

Anyone out there use a MacBack Plus scsi tape unit? We 
sold one to a customer last week and when I went to set it up I ran 
into problem after problem. The unit itself is pretty well made, 
clean looking, quiet... Reading through the several page “рге- 
liminary' manual I found noreference to hooking it up to a Мас+. 
Not one word. They did write several paragraphs about using it 
with their 512k SCSI port adapter. Lot of help that does Mac+ 
users! Being the hacker I am I tried it anyways (What Mac user 
needs instructions!). I hooked the 50 to 50 SCSI cable to my 
DataFrame and to the MacBack. When I tried to boot — nothing. 
Being that the Macback is silent and it has no power light I tried 
several times with the power switch in each position. Still 
nothing. It was time to call tech support. Looking in the manual 
I couldn’t find their phone number nor their address. Not even 
what city they are in! After a number of calls and some research 
I finally found that they are in Santa Clara. When I called I got 
a recording saying that the number was disconnected. Some 
more calls later I found that they moved to a new location. The 
tech person I eventually got through to was friendly enough but 
didn’t even know what a mouse is. After each question he put me 
on hold to ask someone else the answer. Finally I asked to speak 
to his boss and was able to get some help. They suggested I 
change the ID# of the tape drive. Still no go. They also had me 
try different cable configurations with no success. The verdict 
was DOA. Send it back. 

That was yesterday. I'll keep you posted on how things go. 
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So far, a terrible manual, no power light, awful support and a dead 
onarrivalunitleaves me unimpressed. Arethere ANY good tape 
backups out there? [Try the new 40meg tape backup unit from 
SuperMac Technologies. Should work great with DataFrames, 
since both are by the same company. New at the SF Mac Expo this 
week. -Ed] 

Hard Disks: This Is getting silly 

From: The Psuedohacker 

Hey guys, this is getting silly. The continuing debate 
between the Proapp 40S and the Dataframe is kind of pointless 
now. Everyone should be convinced that both drives are excel- 
lent products. I’m not just saying this because Jim is a friend of 
mine. I recently bought a ProApp 40S for a client and it is hot 
stuff. I did do some testing with it on my own before I delivered 
itto the client, and yes, it’s true it’s notas fast as my Micah AT20. 
But then again, Proapp is still in business! I’m having my doubts 
about Micah. 

Jim is right. The 40S is incredibly quiet, DURABLE, and 
fast. Keep in mind when you’re discussing differences of 55ms 
versus 162 ms, lets be real. The average person will NEVER 
notice it. You're talking 1000ths of a second. 

Obviously Scott is sold on his Dataframe. I’m glad for you. 
Now why don’t you guys go on to other topics like setting up a 
user defined bench test, i.e. how fast can Excel load a predeter- 
mined file, of a predetermined size. How fast can it save?, etc. 
Get down to some criteria that really mean something to the user. 

From: Macowaco 

I love the debate. I also love both drives. There is another 
couple of factors that must be considered. One is the nifty factor. 
How nifty do the users think the thing looks or acts....Both win. 
A more important factor though is how easy is it to communicate 
with the HDs producers. Iomega is about to get nailed by actions 
taken by me and others at my co. due to their incredible stupidity. 
The story will leak to the press too. Tuff noogies on them! 
ProApp has been very cooperative, while DataFrame is a no 
show. I just wish I could have one at home..., but I’d rather wait 
three months so that the only speed factor will be the HDs 
performance and not the ext SCSI throughput. 

Disk Drive Dementia 

From: Bob Denny, Editorial Board Member 

Well, here I am in the middle of the great disk war. I am 
testing a PROApp 40 and (hopefully soon) a DataFrame 20XP. 
After bumping into Mac Scotty and finding out what the “XP” is 
.. I’m AGAHST! If I understand him, the XP upgrade is 
essentially a re-written SCSI manager (done the right way, I pre- 
sume). They put the additional code in a ROM in the disk drive, 
then their boot driver reads it in and replaces the Apple SCSI 
manager with their own (or at least part of it). Uh ... at least that 
is my best guess. In any case, I’m aghast because DataFrame 
folks had to throw out the Apple SCSI manager to get the 
performance. 

[I'm using the Dataframe 20XP and love it! Fast, no prob- 
lems. I’ve ordered the 40XP. They also work fine daisy chained 
with Apple SCSI drives as I’ve tried that too. -Ed] 

Speaking of sector interleave, I beg to differ with opinions 
expressed here before. The ONLY reason to interleave sectors on 
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a disk is to compensate for an interface that can't handle the full 
data transfer rate of the disk. A given disk drive has a ‘native’ 
transfer rate that depends on the bit density, data coding and 
spindle speed of the drive. If the interface to the computer is too 
slow for the drive's data rate, then the controller chokes on reads 
(from disk) and starves the disk on writes (to disk). When this 
happens, the transfer must be suspended until the interface 
catches up. This kind of error is called a “data late error". 

Normally, when a disk is formatted, the sectors on a given 
cylinder are numbered sequentially. However, the controller 
looks for the sector's header when told to read a given sector. It 
does not transfer the data until it sees the header (with the sector 
number) sector it is looking for. Therefore, you could write a disk 
formatting program that numbered the sectors in any order you 
want. If they are numbered in other than physically sequential 
order, they are usually “interleaved”. For example, instead of 
1,2,3,4,5,6,7 you might number them 1,5,2,6,3,7,4 (the example 
shows 2 to 1 interleaving). 

Interleaving the sectors on a disk effectively reduces the 
drive's transfer rate by inserting “dead time” between sequen- 
tially numbered sectors. Take the above 2:1 interleaved format 
for example. Let's say we're transferring 4 sectors starting at 
sector 1. We see 1 (go) then 5 (oops, wait) then 2 (ok, go) then 6 
(wait) then 3 (go) then 7 (wait), then 4 (go). The 2:1 cut the 
average transfer rate in half. 

Why interleave? Suppose the interface was almost as fast as 
the disk. After the first sector comes off the disk (we're reading) 
the controller is a bit behind getting the data into the host 
memory. But come hell or high water, here comes the second 
sector. Well, the controller just isn't ready yet ... DATA LATE 
... and now we have to wait for the disk to spin clear around until 
the second sector is again under the head, at which time the 
controller is (surely) ready and the second sector may be read. 
Well... if there are 32 sectors on a track, this could cause a slow 
down of a factor of 32!!! So the 2:1 interleave is the lesser of 2 
evils, since it only causes a 2 for 1 slowdown. 

Now THIS IS IMPORTANT!!! The sector interleave is 
NOT a measure of performance! Just because the Micah and Dat- 
aframe XP use 1:1 interleave and the PROApp uses 5:1 does 
NOT mean the PROApp is 5 times slower to transfer. My guess 
is that the native data transfer rate of the drive in the PROApp is 
alot faster than that for the other drives. The PROApp would be 
using 2:1 interleave or maybe 3:1 even if it could transfer at the 
XP rate. 

In other words, the drive in the PROApp is probably capable 
of the highest performance of the bunch, but it is relegated to the 
substandard performance of the Apple SCSI interface. Only the 
DataFrame guys have figgered out how to replace the Apple junk. 
So, for the time being, the benchmarks look good for the Dat- 
aFrame. But what will happen on the Aladdin or the Paris? Do 
you think Apple fixed the SCSI manager? [We invite SuperMac 
Technologies to respond to this challenge and explain how their 
ROM patch works or will work on the new Macs. -Ed] 

List manager 

From: The Atom 

I’m trying to get a list of text items (1 col, about 50 rows) to 
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work using the List Manager- but I’m having a terrible time 
dechipering IM on the subject. 

First, it says you can have the LM define cellSize itself if you 
don’t pass ita CSize when you define the list. HOW do you not 
pass a parameter? I tried setting it to O (strange results) and 
anything else I could think of, but no dice. 

And how do set it so only one cell can be selected at a time? 
I tried MyList^^.SelFlags:-lOnlyOne; but you can still select 
multiple cells with the shift. 

Also, do I need to create my own scroll bar along with the 
window? I need only the vertical one, but setting ScrollVErt to 
true in the Lnew call doesn't do much. No scroll bar appears. 

Also having some problems with the window notredrawing 
properly, but I need to find out how to fix the above bugs first 
before I look at that . 

From: Chief Wizard 

Idon'tknow how old of a devlopment system you're using, 
but for a long while the code that Apple sent out with the List 
Manager had a bad bug. 

If you look in the declared record for the list, you'll see two 
fields declared as BYTE. You need to change this to SignedByte. 
You see, a Byte actually takes up two bytes, and a SignedByte 
takes only one. 

If you had the wrong interface, you wouldn't be able to 
access the record correctly. 

From: The Atom 

Is there any simple way of including a small icon at the 
beginning of each line in a list manager window? (to make a list 
of names with doc. or folder icon before like SFGetFile (HFS)) 
Or do I have to make my own List definition? 

From: Don 

Yes, you have to write your own list definition to put little 
icons next to your text. You can get the source code to the 
standard (LDEFO) list definition on most BBSs ... including the 
MouseHole DL... if that helps. Actually it shouldn't be that hard, 
but still it's definitely NOT one more thing you wanted to do. 
Presently (tonight in fact) I'm working on a DÀ in Pascal that 
uses the LM. I'll post any clever insights (HAH!), and would 
appreciate you sharing yours. It never hurts. 

From: The Atom 

Can you tell the list manager what font to display text in? I 
was just thinking, if space was less problem than development 
time, you could just include your own font that has a couple 
characters re-defined as the small folder and Doc icons.. Then 
just include those before the name of the cell. 

I’ve finally gotten everything to work, sort of. The only 
problem seems to be with my handling of Activate events. I have 
multiple windows, each with its own List.. Everything seems to 
go right until I bring one of the windows to the front (by clicking 
on it) - the vertical scroll bar will not work! It acts like I need to 
activate the scroll bar or something. Any ideas? I do the LActi- 
vate but nothing else. 

From: Don 

TheList Manager will use whatever font the current grafPort 
is set to. Just make sure you set them before you call LNew. As 
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for the activate problem, are you sure you're passing the handle 
tothe correct list? A silly question, but I made this kind of mistake 
with TextEdit recently. You might try a few Control Manager 
calls just for the heck of it, like DrawControls or HiliteControl. 
Remember, you can get the ControlHandle to your scroll bar 
from the list record. The only other problem I think it might be is 
you’ re not processing the MouseDown event properly. Where do 
you store the rectangle that the scroll bars are in? You might 
check the variable and see if it’s still valid after an activate event. 
By the way, are you writing this in LightSpeed, TML, Turbo or 
MPW? 

From: The Atom 

I’m using Lightspeed- I checked the handle, its the same 
handle as when I created the window so that seems ok.. I tried a 
HiliteControl (ODD(Event.modifiers;List^^. VScroll) but it 
didn't make much difference. 

Ihave now noticed that its not just the scroll bar that doesn’t 
work- if you try to double click an item from the new window, it 
doesn't catch it.. Just thinks you clicked once. 

Also, it seems like if I re-size the window, sometimes it 
becomes active and both the scroll bar and double click work. 

What is this about a scroll bar rect? I haven't done anything 
with the controls other than make sure to set the view rect -15 to 
allow room for it. Do I need to keep track of the scroll bar also? 
[See the January issue for a working example of scroll bars, 
windows and re-sizing events. Apply that code to your list 
manager task. -Ed] 

TML Source Library 

From: John S. Lee 

I did purchase it about 3 mos ago. I found them useful in 
SOME aspects! It really does shine on the code to generate fancy 
menus,windows,controls, which I guess is good for some appli- 
cations. My programs are not window intensive so they had less 
use for me that they might for others. You can expect the 
following form them: 

PopUpMenu, SFGetFile, SplitBars, Speech, Print, Dumbterm, 
RegMdef, GrafMdef, RegWDef, FancyWdef, NiftyWdef, RegCdef, 
FancyCDef, Екеу Example, DescAcc Example, ReglDef, Fancyldef. 

With all of this you would have thought that : 

1.) They would have included additional documentation to 
change the include files to just USES MacIntf; (Maybe I have an 
old version [it is 1.0], but I have TML 2.0). 

2.) They would have had at least several graphics demos, 
both 3d,2d etc. 

3.) The manual does a mediocre job of explaining how the 
program works. 

4.) If you are NOT well versed in pascal or are a beginner 
with a high frustation level, wait awhile, become better versed 
and buy it! 

I think that for the pascal hacker who really needs no 
documentation and loves guesswork or rather is well informed 
and likes new ideas this library is heaven. I think that for the price 
there is no better value, especially since there seems to be a big 
code hogging thing going on right now with all of the program- 
mers. 

Most of the library you will be able to use in some way, the 
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concepts are well represented in the actual source. Whether or not 
you should buy it is up to you, but one thing is for sure. It would 
take you quite awhile to find a selection of source so well tailored 
for a specific development system. 

P.S. If you really want to do some fun stuff try MacExpress 
by ALsoft,Inc. I received mine about 2 weeks ago and the results 
are well past amazing! This thing handles all of your event 
proocessing for you it also handles all of the panel events etc. The 
time that you spend coding is reduced to writing your OWN 
procedures instead of worrying about how it will actually 
get(pass) the event for said procedure. The window extensions 
are great, and if you ever wondered about how the wiz bang guys 
get all of the neat status displays and the like, MacExpress has the 
answer. It is difficult to learn at first, but after a few hours itis well 
worth the money and effort. No MPW for me. I’d rather have 
MacExpress. 

MPW Pascal 

From: Jack Howarth 

Does anyone know if MPW supports some form of string to 
real number conversion analogous to the ReadFrom in TML and 
LS Pascals. I had a routine to do this for version 1.0 of TML, but 
it’s alot of code to do in a high level language. I really would like 
to put a call to ReadFrom and StringOf in a TML Unit and 
somehow link in the paslib functions that do these calls. Would 
it be possible to sucessively port this into MPW as these are really 
pascal library functions that must be linked in at some point? 

From: Rick Boarman 

I don’t know anything about ReadForm but MPW supports 
all the SANE Str255 to Real (Single, Double, Comp & Extended) 
conversions. It even has a slick parser which can be used for 
interactive input of numeric values. 

TE 'TextBox' routine 

From: Beaker 

My MIDI Patch Editor, ProEdit, uses the TextEdit routine 
TextBox to draw the titles of the sounds in a patchblock window. 
There's 32 calls per window, and up to four windows. It was 
taking a full two seconds to draw (update) the window, so I 
decided to take a look at TextBox with MacsBug. You wouldn't 
believe it. 

Insteadof really writing a TextBox routine to simply draw 
text, they create a TERec for the text, set up all the rectangles, call 
TECalText, then TEUpdate. No wonder it's so darn slow. 

Has anyone out there rewritten (i.e. written their own) 
TextBox routine? If it’s PD, I'd love a copy, in whatever 
language. 

Printing Problems 

From: The Corsair 

I am having a bit of a problem printing a specified range of 
pages. Here is what I am doing: 


firstpage = (**printh).prJob. iFstPage; 

lastpage = (**printh).prJob. iLstPage; 
(**orinth).prdob.iFstPage = 1; 

(**printh2.prJob.iLstPage = 999; 


forCj=f irstpage; j<lastpaget1; j++) 
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( 


ny printing code 


Now what happens is when I type in a small number into the 
print dialog like from page 2 to 4 it works fine, but if Itype in like 
from 8 to 10, it doesn't print anything. Now, itis going through 
the loop just fine and it is not getting any print errors. Another 
thing I did was to plug fort j=8; j<9... into the loop and in the print 
dialog I typed in the range of 8 to 10 and it still didn’t print, but 
when I hit “all pages" it printed pages 8 to 10 just fine... 


for (j=1; 3417; j++) 
( if(PrError() == noErr) 
( 
іпсргі(()%32-2); 
HLockCpr inthand); 
ptr = pl = C*printhand); 
PrOpenPage( printPort, ØL ); 
if(PrError() == noErr) 
( 
MoveToC printRect. left*leftMargin, 
(lineBase = printRect.top*lineHeight) 2; 
do 
( 
„1% PrintLine: */ 
while (Cptr<=(*pr inthand)+count) && 
(*р{г++ іг Cchar)’\r’)) ; 
if CClength=Cint )(ptr-p 12-15» 0) 
MyDrawText(pi, length); 
MoveToC printRect. left+lef tMargin, 
(lineBase += lineHeight)); 
pi = ptr; 
) 
while (ptr<C*pr inthand)+count ); 
PrClosePage( printPort ); 
) 
) 
) 


Now, the problem is that if I specify a page range or print 
high quality or standard quality on the imagewriter it goes 
through the loop, gets no prerrors and does not print anything... 
the incprt routine setts up the printhand with the next page to be 
printed - 5300 chars - 81 X 66 lines... 

Theorbo Crwth 

Are you sure your problem is not in the printing code itself? 

If the loop is travelling fine and the numbers are correct, 
maybe it's the printing function you have devised. Also, it's 
better to have your loop structured as: 


forC ... ; j <= lastpage; ... 
lastpage + 1; ... 


rether than: forC- 53 X 


Since you are using a complicated set of structures and 
members make sure the datum isn't getting munged somewhere. 
Almost sounds like an allocated array isn't large enough. 

If it’s running through the loop and printing out in draft 
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mode, but the same loop in imagewriter mode prints nothing then 
it seems to me that the instructions for the imagewriter are not 
correct. I'm not up on that particular printer, but maybe the 
program is not sending the correct information that the 
imagewriter needs. 

Another question I have is does it print out on the screen? If 
уои сап redirect the I/O so the printed file goes to the screen rather 
than the printer you might see your problem. It sounds like the 
program isn't sending the printer what it needs know. On the 
other hand, perhaps it is sending codes that are screwing up the 
printer. 

LS C 2.0 

From: Mcohen 

I just received my Lightspeed C 2.0 upgrade yesterday and 
it's great! In addition to the new features you may have heard 
about (HFS support, etc.) it has a much better stdio library. А 
"generic" Unix program will automatically get a real movable 
window and will automatically support the desk, file, and edit 
menus (which will be automatically provided if you use the 
"automatic" stdio initialization). all console I/O functions allow 
desk accessories & FKEYs to be used. The compiled code is a bit 
smaller - a 122K application with 1.0 is now 112K. Oh yes, LS 
C 2.0 supports function prototypes and INLINE ASSEMBLY 
LANGUAGE! 


Vol.3 No. 3 


Summary of the New Mac Announcements 

From: Misc. Posts by David E. Smith 

AppleShare, the Apple networking software, was an- 
nouncedatthe Seybold conference, but it apparently requires it's 
own dedicated Mac, which seems like you give up something 
here compared to TOPS. One thing is sure, networking has been 
given the green light by Apple and we can expect to see a busy 
market for high density "library" disksto service those networks. 

Yesterday Apple put on a sneak preview of their new 
hardware. They had a couple of production units along with a 
prototype Mac II. Here are the details on the new machines 
expected at the March 2nd product roll out. 

The “Alladin’s” official name will be Macintosh SE. The SE 
sits 1.5" higher than the Plus, to provide room for adding either 
a hard disk, or second floppy to the internal 800K floppy drive. 
Memory is expandable from 1 to 4 mb RAM. The CPU is nota 
68020, but simply a 68000 running at the same clock speed as the 
Plus, 8 mHz. However, a single 16 bit 96 pin slot is available to 
add third party "Prodigy" type accelerator boards with 68020/ 
68881 chips and several will be available shortly. It is possible 
these accelerator boards will also be able to increase the clock 
speed to 16 mHz. The slot is not user accessible which means you 
have to open the case to get to it. А knockout is provided for 
cables. The motherboard is similar in function to the Mac Plus, 
but a new design. ROM memory is increased to 256K, the 
internal hard disk option is supported by an internal SCSI bus in 
addition to the external SCSI port. Two serial ports are provided 
as are two Desktop Bus ports for the mouse and keyboard like the 
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Apple II GS. This bus provides for chaining additional mouse 
type devices. The display is a 9" B&W monitor with 73 dpi but 


‘with an improved display sweep said to provide a 20% increase 


in screen updating. The battery is a 7 year battery contained in a 
soldered battery holder inside the machine. In other words, not 
easily replaced. The infamous power supply has been beefed up 
to 80 watts. The cabinet is platinum in color and similar in shape 
to the present Mac case. However, there will be no upgrade path 
from the Mac Plus. An ominous development is the availability 
of 5 1/4 inch disk drives for MS DOS, and third party 80286 
accelerator cards. 

The Mac II code named “Paris” is expected to be in limited 
supply until at least June. The features however, appear to be 
what everybody wants. The processor includes a 16 mHz 68020 
with a 68881 FP co-processor. 256K of ROM same as the Mac 
SE, but with an additional 256K ROM socket for a page memory 
management unit. Memory will be expandable from 1 to 8 
megabytes using 1 mbit chips! The open architecture consists of 
six NuBus type 32-bit slots. The I/O configuration is similar to 
the SE with 2 SCSI ports, 2 serial ports, and 2 desktop bus ports 
for the mouse and keyboard. Two keyboard options include 81 
or 105 keys. The built-in 5 1/4 inch hard disk comes in 20, 40 or 
80 mbyte configurations. A four voice stereo sound chip is 
included. The video options include a 12" Monochrome 640 by 
480 display with 16 gray scales or a 13" Sony trinatron color 
monitor with the same resolution supporting 256 colors from a 
pallet of 16 million using an 8 bit plane. Quickdraw toolbox 
support provides for 32 bit planes for third party video cards. The 
vertical scan rate is 66.7 Hz. A 20" monochrome monitor with 
1120 by 880 resolution is in the works for a December release. 
The notorious SANE floating point package has been speeded up 
by a factor of five in this machine. Calling the 68881 directly is 
expected to increase performance by a factor of 20. A UNIX 
system 5release2 operating system with Berkeley enhancements 
will be available with Sun network support. A 40 mb tape backup 
unit will also be available. Those who have seen the machine 
report they were "completely blown away" by the color and the 
speed of this baby. 

Rumors on the new printer are that it will be a postscript 
printer, but notan Appletalk device. Also it won'tbe available for 
a year yet. 

A new version of MacTerminal (2.2) will support user 
defined macrosor function keys. They reside on the bottom of the 
screen. 

A new MacDraw will fix the old text bug, does free rotation 
and multiple scaling. And it will cost plenty! 

From: The Atom 

WHAT? 

You mean the awesome SE we've been waiting for is simply 
a larger Mac+ with a single slot? WHOOPIE! I sure hope thats a 
rumor, since I can't afford $5000 for a Paris and I was definitely 
looking forward to 16 mhz on some type of lower end machine. 
[Sorry Charlie..., but the thrid party people will bail you out. - 
Еа.) 

From: Macowaco 
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In my opinion, the SE is a step in a good direction...if you 
work for a big company. If you're like most of us here....no, it 
stinks. It will sell and sell big. Our company already plans on 
buying more SEs than IIs and we're buying lots of IIs. The SE is 
basically all that the + still lacks before it can become a truly 
systems oriented workstation. The main difference will be the 
Ethernet card, and later the addition of the CD ROM. The CD can 
contain Inventories, Tax tables, HUGE dBs while the Ethernet 
connection allows for REAL data and resource sharing and at 
high speeds. For an Engineer.....no, for an officeworker in any of 
hundreds of settings where they currently use PCs, or dumb 
terminals (I equate them) all tied together....a big yes. 

Prototyper 

From: Lsr 

I talked to one of the people involved with Prototyper. 
(Either Smethers or Barnes, I forget which.) You can build an 
application very quickly, but as far as making it into a real 
program you have to work from the block diagrams that Proto- 
typer generates. They don't have any way of generating code or 
of getting a textual description of the interface. (My interest was 
in prototyping with Prototyper and writing a translator to Object 
Pascal/MacApp.) 

On the other hand, ExperTelligence was demo-ing some- 
thing called Exper-Interface-Builder. This is a system developed 
by a person in France that lets you prototype an interface. (I 
didn't see the demo at the Expo, but I did see it once at a 
conference.) The difference here is that it generates Lisp code as 
output, So you can incorporate it into a real application. 

From: Dr. Dog 

Nevertheless, an application like Prototyper could be pretty 
helpful.I work ata medical computing department at the Univer- 
sity of Utah. We have developed several Mac programs under 
grants from the National Library of Medicine. The hardest thing 
we do is trying to get the type of interface desired standardized. 
Usually, by the time the program is far enough along to test the 
interface on prospective end-users, hundreds of hours of code- 
writing have gone by. We often end up making major changes 
after getting user suggestions. I think Prototyper could be very 
useful to *dummy" up an application. One could then try out the 
"feel" of the program on the user before code writing even begins 
in ernest. 

MPW ver 1.0 

From: Randy Saunders 

I just got my MPW update from APDA. I have new versions 
of MPW and MPW Pascal. What I am trying to figure out is, 
what's new. Itseems that nobody at APDA knows what bugs are 
fixed. At least I got a known bug list with the B2 version. The 
manuals are bigger, but the type is smaller and there is still no 
index. Almost all the files say they were created 9/4/86, with the 
interesting ones (Shell and Pascal) dates about 10/2. [MacTutor 
has also received our 1.0 MPW update. Thank you APDA! -Ed] 

CricketDraw and GreyPaint 

From: Macowaco 

CricketDraw is far from complete. It takes too long to print 
the good stuff (probably for good reason), but more importantly 
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it can't read large Postscript files a la Pro3D for text annotation. 
Too Bad! 

Try GreyPaint's RubberStamp tool then Laserwrite it. It 
maintains the gradual grey scale the way Pro3D and Cricket do. 
It looks like someone smeared toothpaste on the paper! 

MacExpo and various other things 

From: Michael J. Wallace 

At the Expo , there was a guy at the BMUG booth trying to 
get dealers to sign up and buy his service. What were these 
services ? Colored Macs: Green/Red/PINK!/Black/ Yellow/ 
Platinum/ White. Totally psychadelic ! I prefer Red or Pink. Then 
you go to C.ITOH and get one of their FIVE pack color Pastel 
disks (single now, double soon) and be totally for real. 

Prototyper: I do want to see more. But they had a big booth 
and ONE repeat ONE lousy Mac. Won't be ready until Spring - 

read June. Those who saw VIP think it's pretty lousy! Good 
ideas, just bad implementation. [Others came by the MacTutor 
booth and said they thought it was great! -Ed.] 

Mac Expo hits: Hard disks EVERYWHERE. The LOWEST 
is Jasmine at $585 for a 20 meg. Be REAL careful, they were 
collecting money with NO FIRM ship dates, everyone ELSE had 
them in the booth! I got a Reflex 30 meg for $895. Northern 
Calif. brand. Bit noisy, but just as fast. [A new company has 
announced a 10 Meg SCSI hard disk for just $399! The idea is to 
push it as an external disk drive replacement, same price. Watch 
for more info in MacTutor. -Ed.] 

FullWrite Professional 

From: Bob Denny 

I am REALLY surprised to see no messages about 
FullWrite. Isaw the demos at MacWorld & was blown away. It’s 
everything Word 3.0 is and more (MacDraw built in, auto wrap 
around irregular objects like RSG only better, VASTLY easier 
user interface and much more). Scott Weiner & gang have 
outdone themselves. Watch for this RSN. 

LISA Hard Drive 

From: mouseFur«tm» 

To everyone who answered my plea for help about the hard 
drive problems, THANK YOU very much. I am still on hold and 
have been told that APPLE is not presently shipping parts, 1.е.. 
the replacement H.D. (for Lisa) that I ordered. The truth is the 
dealer that I have using appears to be on hold for slow payment. 
It's a shame that they couldn't be more up front. Their situation 
would certainly be easy to understand in view of current day 
events. 

Sun up in Utah has been heavily advertising all sorts of LISA 
configs. for sale. (& parts). When I called them, they said that a 
hard drive is only available in a machine purchased from them. 
Are they supposed to be the folks that bought up all of the 
remaining LISA goodies? 

NetWorkers in San Leandro seems all LISA knowing and 
has agood supply of working information and parts. They are ad- 
vertising a 20 & 40 Meg replacement hard drive as a LISA 
update. When I inquired, they reported they are still in the 
development phase! 

NetWorkers does have a release version of a modified or 
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fixed MacWorks that is reported to allow the finder to manipulate 
more desktop files than it was designed to do. Their fix is claimed 
to eliminate the crash to a dark screen, with a sad Mac icon and 
code F00064. I have ordered a copy and will keep M-Hole 
members advised if there should be any continuing interest. 

F00064 Bomb | 

From: Rick Boarman 

MacZap's HFS Recover version 4.5 will fix the Sad Mac 
bomb on a Mac XL with no problems. It adjusts the entry tables 
as needed. I've had to use it several times myself. 

MacZap Recover 

From: Jim Reekes 

Incredible utility! Every hard disk owner must purchase this 
program. I've recovered over 30meg (1525 files) with it. 

This drive was not recognizable by the Finder, which only 
asked me if I wanted to “Initialize or Cancel”. I also had a backup 
data disk created by HFS Backup, but while restoring, the 
program gave me an 'error while reading disk'. MacZap to the 
rescue. It recovered the file. 

Also had a drive that bombed while rebuilding the desktop. 
Apparently the drive had a directory problem and the Finder 
couldn't build the desktop. MacZap helped me again. It has a 
‘kill the desktop’ function which allowed me to boot the Finder 
and copy the files. 

Stepping Out 

From: Don 

I’ve just found out some interesting stuff about Stepping 
Out, a new program by Berkeley System Design. It installs a 
virtual large-screen display in memory. The size of the display is 
configurable and you scroll around it by simply moving the 
mouse pointer to the edge of the screen. 

Presently, the virtual display is limited to 2048 pixels wide 
by 1368 pixels deep, or 16 times the size of a normal Mac screen. 
BSD is releasing an update in a few weeks that will allow a virtual 
display limited only by Quickdraw and available RAM. Person- 
ally I like just 700 by 900 pixels, enough to show an 8 and 1/2 by 
11 inch document. 

Wes Boyd, the president of BSD, has told me about a few 
other goodies in the future. One feat they will attempt will be 
fixed menus, i.e. always keeping the menu bar at the top of the 
screen. They will also try to get Stepping Out to work correctly 
with REAL large screen displays. I know it bombs something 
awful when you use it on an E-Machines’ The Big Picture. 

I think it’s a great help for those graphics intensive programs 
where scrolling through documents by conventional means 
seems to take forever (Let’s see a show of hands for those with 
MacDraw polygonitis!). 

New ResEdit Bug! 

From: Ant Killer 

There is a bug in the New ResEdit 1.1-d. I found it after 
adding and removing some resources from my System file. I had 
ResEdit in my external drive and my system disk in the internal 
drive and chose Quit from the menu without closing and saving 
each window I had opened (it used to work!). Anyway it didn't 
ask if I wanted to save the changes, it just quit! Well, Ishut down 
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and tried to boot the disk, but it had thrashed my System file 
(Ah!). The moral: if you're gonna use this version of ResEdit (it 
is nice otherwise!), close each window before quitting! 

Servant/Finder 

From: Gary Voth 

I was quite distressed to read the posts about Apple's plans 
(or lack thereof) for Servant. I HOPE what this means is that 
Apple has no plans to release Servant as we know it as a Apple- 
labeled product— but that Servant technology may still be 
incorporated in future versions of the Finder. (In my view, Apple 
MUST do this in order to compete with impending multi-tasking 
versions of MS-DOS and Microsoft Windows.) [Andy is com- 
mitted to releasing Servant to the marketplace one way or 
another, according to published reports in InfoWorld. -Ed.] 

I also concur in the criticisms of Andy's user interface. 
Servant is a beautiful hacker's product: full of “insanely great” 
things like the scrolling hand, multiple-magnification views of 
the directories, and a resource editor. Unfortunately, none of this 
stuff is anywhere close to the mainstream of Macintosh software 
design. The lack of scroll bars is simply unacceptable: if you 
want to provide “hand scrolling," then do so via an option-key 
modifier (which has already been standardized in other applica- 
tions), or let the user configure the program to his preference. 
FORCING you to do something іп an “insanely great" way is 
rather similar to the attitude adopted by the original Macintosh 
designers, who gave us a computer that didn't even have cursor 
keys! 

Frankly, making an easy-to-use resource editor available to 
the end user is like giving a child a loaded gun. (This remark is 
NOT intended to be disparaging toward the abilities of end users, 
but to point out that it is simply inappropriate for their needs.) 
This can be a very dangerous tool. And as a software developer, 
I don't particularly want people “customizing” my programs in 
funny ways. I'm also sick and tired of seeing MUTANT Mac 
desktops in half the Apple dealerships I've been in. Every kid 
who learns how to draw flies buzzing around the trash can icon 
has probably turned off potential business buyers. 

I've put together a list of things that I'd like to see the 
Macdesktop metaphor evolve to. My list is obviously personal 
and subjective, but Ihave a great deal of experience with both the 
Mac and other personal computers to draw on. I've posted this 
list as the next message. Your comments are welcome. 

Finder/Interface Extensions 

From: Gary Voth 

This is a list of extensions to the Finder and the Macintosh 
user interface. It is my opinion that Apple needs to hear these 
ideas and others from the development community. Anybody 
interested in participating in a “White Paper” on the evolution of 
the desktop environment and Macintosh user interface should 
post a message on this board. Га be interested in hearing any and 
all comments... 

In my view, the Macintosh Finder should evolve in anumber 
of ways. It should of course incorporate Servant’s salient fea- 
tures: multiple application switching and management of a single 
desktop environment. But far more useful to people than 
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Servant’s bells and whistles might be some of the following: 

o Font and Desk Accessory Management 

This is “appropriate resource editing” that end users really 
need. The Font/DA Mover is a utility that really should be part 
of the desktop environment. 

o HFS Backup and Restore Capabilities 

Of course this should be built into the Finder. 80% of all 
business computer systems are sold with hard disks. And Apple 
doesn’t even provide a SEPARATE utility for the HD 20! 

o Background Print Management 

Asa true shell (running other applications in separate heaps), 
the Finder should intercept application calls to the Print Manager 
and handle all print queuing in the background. 

o Expanded Desktop Management 

How about the ability to sort your directories by date, size, 
kind, or name IN THE ICON VIEW? Or the ability to directly 
launch a named application without having to mouse through all 
the folders? Or putting the Find File DA into the Finder itself? 

о User Interface Extensions for the Keyboard 

You should be able to use the Tab key to select folders and 
applications within a window, then press Return to open one. 
Command/up arrow should move one level up in the directory, 
and Command/down arrow should go the other way, etc. The 
menus should also by accessible via the keyboard. 

о Scripting 

The lowly MS-DOS batch file can sure be a powerful way to 
shelter novice users from the complexities of the operating 
system. And for the experienced user, it can automate a lots of 
repetitive tasks: ask programmers, how many times have you 
wanted to do something like;"DUPLICATE all QUED docu- 
ments in «folder» using «name.bak»; COPY all .REL files in 
«folder» to floppy; LAUNCH QUED using all TEXT docu- 
ments beginning with “MyApp...”, all in one fell swoop? 

о Optional Command Language Interpreter 

Dare I say it...? 

о User Interface Extensions for Windows 

A Windows menu should provide tiling and stacking op- 
tions. А command key should cycle through the open windows 
from front to back. Etc., etc. 

This list could obviously go on. I haven't even touched on 
some of the capabilities that Unix or Pick users enjoy. Obviously, 
the challenge is to build in a rich level of functionality WITH- 
OUT adversely affecting ease of use or intuitive operation. The 
Mac designers did a great job in the beginning, but the Finder has 
remained essentially stagnant since 1984. Today's users are 
demanding a lot of their computers, and the software technology 
exists to provide it. Let's get to work, Apple! 

MacApp and Licensing 

From: Bill Evans 

The fear of Big Brother (a little like Big Blue, I guess, or Too 
Big For His Britches) may be based on fact. December 1986 
MacUser, page 43, says: “Apple is actively urging game publish- 
ers to publish for the IIGS and not the Mac. The only Mac games 
in 1987 will come from smaller, ‘maverick’ publishers. But there 
are some really great ones already in beta test." 
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One has to wonder when Apple's interest in "actively 
urging" people not to publish software which is incompatible 
with Apple's marketing strategy will spill over into the MacApp 
licensing process. Anybody out there want to make himself a 
bundle by producing a MacApp substitute and license it to 
anybody who wants to publish anything they want? It would 
have strong appeal, I'll bet to a lot of free spirits out there, even 
if they haven't had any difficulty licensing the use of MacApp 
yet. Apple's uppity attitude gives me the creeps. 

MicroPhone wish list 

From: Bill Evans 

I'm using MicroPhone 1.0, so my wish list may not reflect 
what's already in it, but here goes: 

1 — While you're in the Finder, it’s possible to double-click 
a MicroPhone document, and MicroPhone will then (if you've 
set up the script right) dial the service, log you in, and place a 
"quit" button at the bottom of the screen. So when you're 
finished, you can click the quit button and MicroPhone will log 
you out. Too bad you can't tell the “Quit” script also to exit 
MicroPhone, leaving you back in the Finder where you started. 

2 — It's possible in a script to "Send Text String". It would 
be nice to be able to “Send Hex String" as well. 

From: Frank Boosman 

My personal wish list for Microphone: 

o That the communications language become more gener- 
ally powerful. For example, it would be great to have variables 
for use in scripts. 

о That scripts be able to control communications parame- 
ters. The inability to change things like baud rate is a big 
drawback. 

о I would like to see Dennis abandon the “window that isn't 
a window" at the bottom of the screen—the area where he puts 
up control buttons. It's non-standard and I would rather see him 
use a palette-like arrangement. And if he goes to a palette-like 
window, why even have buttons? Make ita scrolling list for more 
flexibility. 

o Ithink Microphone uses "funny" memory allocation. Try 
reading a bunch of messages, enough to fill up memory. When 
you get close to running out of memory, Microphone suddenly 
slows toa crawl. It gets especially bad if you then open up a desk 
accessory. Dennis needs to include a feature to allow users to 
select how much text to save off the top, and a command to clear 
lines off the top. 

o Microphone's “Save Selection As...” command works 
fine, but selecting text screws up the scroll bar setting for a 
moment. It's difficult to explain; just try it and you'll see what I 
mean. 

Of course, none of this means that Microphone still isn't the 
best communications program around for any microcomputer— 
but it could use some touching-up. 

From: Bill Evans 

Another MicroPhone wish: When Microphone dials a 
service, and the service doesn't connect, MicroPhone always 
waits about 30 seconds before it gives up. It would be nice if it 
gave up when it got a message from the modem saying “МО 
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CARRIER" or (for those who can manage this miracle) “BUSY” 
or the like. That way, we can use the S7=whatever command to 
wait for longer or (heh, heh) shorter than 30 seconds, and have 
MicroPhone figure out what we're up to. This one I haven't 
written to MicroPhone yet, so if you could put it in the wish list, 
that would be very nice. 

ZBasic vs. MS Compiled Basic 

From: Dave Kelly 

The Feb. MacTutor has my observations on the new MS 
Compiler. However, Zedcor has just phoned me to complain 
about the MS Benchmarks which were sent out to all press. They 
(Zedcor) thinks that some of the benchmarks are fraudulently in 
favor of MS Compiler. They are sending me a list of the prob- 
lems with the benchmarks in the next few days. ZBasic is really 
working much better lately. I have version 3.04 beta. It turns out 
that a lot of the problems I have found have been partly because 
I've been trying to program ZBasic in the same way that I do with 
MS Basic. They are NOT the same nor do they claim to be. The 
next few months should show more about which compiler will 
come out on top... Zedcor's ZBasic, the little guy on the block or 
Microsoft with their big corporate image. 

Pascals... 

From: Greg Kostello 

I've worked with TML, Borland and (a little) MPW. For 
speed nothing can beat Turbo. You simply write your program 
and run it. It compiles and runs most programs faster than Apple 
Pascal could interpret them. At UC Irvine, where Macintosh 
programming was taught, our Prof. asked us which pascal we 
preferred, TML or Turbo. Approximately 85% of the class chose 
Turbo, 10% TML and 5% MPW. TML is a more complete and 
advanced pascal. For instance, if you want to use object pascal 
TML 2.0 supports it. Turbo does not do object based program- 
ming but they say they are planning it for the future. MPW is 
incredible. Ithas a million tools. If you like UNIX you will Love 
MPW. The problem 15 it is so damned slow. You can sleep thru 
a compile. Now, if I only had a Prodigy this would not be a 
problem. Enough said. 

From: David Valentine 

I’ve been working with LightSpeed Pascal for the past 
month and find it fantastic for writing little snipets of code that 
you may have wanted to write in in a compiled language but 
didn't feel like spending the time debugging so you wrote it in 
basic. LSP has some tools that are indispensable when learning 
the Mac, like source level debugging and lights bug debugger. 
Ilove it, now if it only had objects. 

MPW THINGS 

From: Cpettus 

I've noticed two strange interactions between MPW and 
TMON, and wondered if perhaps anyone here could give some 
guidance. First, it is apparently not a healthy course of action to 
install TMON from the Shell; I've had a high bomb rate when 
Гуе done so. 

Second, with TMON installed (either from the Finder before 
launching the shell or from the shell) the rate at which the Shell 
responds to typing slows down very noticeably. Normally, the 
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Shell can just keep up with me; with TMON installed, I can easily 
outrun the shell editor. 

Also... 

Just to save anyone the hair-pulling I went through, there 
have been some changes to the syntax of certain items in Rez 
from version 1.0b2 to 1.0 of MPW which render syntactically 
incorrect some of the .r files used in sample programs and 
MacApp. 

First, in ALRTS, the four alert stages were previously written 
out explicitly; now they are array items. What this means is: (a) 
before the first item of the first stage, put a (; (b) after each of the 
three-item groups in each of the four stages except the last, put a 
semicolon instead of the current comma; and, (c) end the group 
with a }. 

Second, to get the document window with a zoom box, the 
previous symbol in WINDs was zoomProc; now, it's 
zoomDocProc (*sigh*, changes, changes). Either define zoom- 
Proc to be zoomDocProc, or do a global replace. 

If anyone can elaborate on this, or has related comments, I' d 
like to hear them... 
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AppleWorld Report 
From: David Smith 


I don't see any Apple World posts this morning so I'll post 
what I saw. The SE is a definite improvement over the Plus. 25% 
speed up due to a big 4K gate array replacing all the memory 
management PALS. From the window level, the SE seemed very 
snappy in comparison to the Mac Plus. In fact, the Mac II did not 
seem that much faster than the SE at the desktop level. The SE has 
256K ROM including improved SCSI and Appletalk stuff. The 
II also has 256K ROM, but not the same ROMS. It has color 
quickdraw, colorized managers (window, dialogs etc), NuBus 
slot package, and 68881 SANE package. The SE also has SANE 
in ROM but not the 68881 version. The integrated Woz machine 
disk interface has been reduced even more to a very tiny custom 
chip! Amazing if your an old Apple timer. The II has a Sony made 
universal switching power supply. The slots and power supply 
look a lot like an Apple II. Its a beautiful single board implemen- 
tation of the 68020/68881 with a whole bunch of custom flat pack 
ICs of various sizes. Both machines have increased custom chip 
density. The ROMS feature new text edit packages that support 
a style record that handles multiple fonts! (At least I think its in 
both ROM sets). Apple's version of Unix on the Mac II allows 
plug in compatibility replacement for a Sun or Apollo worksta- 
tion in a Unix net. And you can still have the Mac window 
interface in a Unix environment. The II is dynamite in the work- 
station market. They said the May ship date on the II may slip... 
The power supply on the SE is also supposed to be better, but this 
was not obvious. However, the SE is a most definite performance 
improvement over the Plus and this message is not getting out 
with the excitement on the II. But the II is impressive, but 


expensive: $3800 bare to $6800 loaded! 
New Product Line 
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From: SpUd PoTatO 
SPUD'S PREDICTIONS 


MacII HIT! 
Color Better 
Monochrome Worse 
Mac SE FLOP 
Apple PC Equipment LIMITED HIT 
Apple Hard Disks ЕГОР 
Apple Extended Keyboard HIT 
Video Card/Expansion FLOP 
A/UX (Unix)FLOP 
EtherTalk HIT 
Universal Monitor Stand WHO CARES? 
Remember, you heard it here first! -Spud 
Mac |! 
From: Lsr 


Here are some of the capabilities of the Macintosh II. 

You can have up to 6 screens (1 per slot). They are 
contiguous (a la Radius). You configure them (position, depth, 
etc.) in the new modular Control Panel. Windows can be partially 
on a 8-bit color screen and partially on a 1-bit B&W screen (or 
anything in between). Quickdraw takes care of all this automati- 
cally. When using color, you generally specify the RGB compo- 
nents. The Color Manager will convert this to the closest color 
the device can display. (This is similar to the way the Font 
Manager works.) Youcan also ask the Color Manager if a given 
color can be represented on the screen. 

Color Quickdraw supports color patterns, which can be an 
arbitrary pixel map. (A pixel map is an extension of a bitmap, 
since each pixel could be bigger than 1 bit.) A lotof stuff happens 
automatically; there was a DA called Magnify that magnifies a 
section of the screen. It works in color. 

Instead of a sound driver, there is a higher level Sound 
Manager. Sounds are generated by synthesizer resources. 
Synthesizers support 1 or more channels of commands. (All 
standard Synthesizers support a subset of the commands so you 
can send the same commands to different ones and the resource 
will execute the commands as best it can.) The sound hardware 
does not take very much CPU time. (There is a custom sound 
chip.) [Apple said they went with their own custom chip on the 
motherboard for software compatibility. -Ed] 

Fortran plotting 

From: Gary White 

You might also want to look at McFace which advertises in 
MacTutor. Nice product for $50. It doesn't have the prefabricated 
plot routines but is nice for enhancing Fortran toward a Mac-like 
interface easily. 

New Mac 

From: Jim Reekes 

Okay, where's the Mac III. That's whatI wantto know. )]» 
reekes <[( 

Mac Il Color 

From: Rick Boarman 

As far as I сап tell from reading Inside Mac Vol. 5 is that 
the upgraded video card will support 256 colors on the screen at 
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one time. 

“..ап eight bit index into a table of 24-bit 

entries would allow a selection of 256 colors out 

of a total range of 16,777,216...” 

TML, MDS, & MacApp 

From: Worker 

I am working on adapting MacApp to work with the TML 
Object Pascal compiler, and MDS 1.0 for the assembler parts (I 
just received MacApp yesterday, so I have only begun). Step one 
was to fix the MDS assembler to accept the percent sign in 
identifiers. I think my patch is Ok, but I’m not sure yet; I will post 
it when I'm sure it's correct, or sooner if someone else is treading 
down the same path as me. Also, if anyone knows of any 
obstacles in my way that will be next to impossible to overcome, 
let me know. [Consulair has bought up the rights to MDS and will 
now be marketing it. You might check with them as they would 
probably be more helpful than Apple has been on MDS. -Ed] 

From: Richard Clark 

I talked to Tom Leonard at the Expo about TML/MacApp 
and he said 1) it needs a new linker to handle Apple's files and 2) 
there's a difference between the way TML and MPW handle 
some feature within Object Pascal. TML *will* be brought into 
line with MPW's syntax, Tom said, and the new linker shouldn't 
be any real trouble, but they're waiting for Apple to license the 
MacApp stuff to them. The upshot of all this: it may notbe worth 
your while to attempt the conversion, unless you're prepared to 
write a whole new linker and maybe a pre-processor for the code. 
[Just remembered: the Linker problem is that TML uses Lisa- 
style segs and MPW uses something else.] 

Renaming FONTs 

From: Jim Reekes 


Since I use LaserPlus fonts constantly and hardly ever print 
on the ImageWriter, I wanted to rename all the Laser ones to 
show at the top of the menu. The only util that I could find to 
change the name of a resource was ResEdit. I changed every 
occurrence of FOND, with the ‘Get Info’ option. But then I 
started to get the double-font name problem. Both old names and 
the new ones were showing up. But opening the FONT resource 
only picked the fontname from the FOND list. So, hold down the 
‘OPTION’ key while opening the FONT resource and you'll find 
where the older set of font names are stored. 

I guess that some of the older programs were still looking for 
fonts names by looking at the FONT and not the FOND resource. 
By the way, while you’re changing names, rename “New Cen- 
tury Schoolbook” to just plain “Schoolbook”. I prefer the single 
quote ( ' ) in front of the font name, that’! put them at the top and 
not be too distracting. 

Mac II software compatibility 

From: Dr. Dog 


Here are some quick benchmarks on a Mac II running in 
competition with a Mac Plus (the Plus has 2.5 meg of ram and 
a DataFrame XP40 Hard disk): 


Word 1.05 CRAM cache off2- Launch from hard disk: 
MacPlus - 6.5 seconds Mac II - 4.5 seconds 


PackIt III v. 1.2 (1 MEG cache)- Time to pack Excel 1.03 
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on hard disk with compression on: 
MacPlus - 7 min 19 seconds Mac II - 2 min 2 seconds 


MacDraw (1 MEG cache on, First time launch), Open Mac 
Оган: 

MacPlus 15 seconds Mac II - 7.5 seconds 

Exit to finder: 

Mac Plus - 6 seconds Mac II - 5 seconds 

Second time launch, Open Mac Draw: 

Mac Plus - 5.5 seconds Mac II - 3 seconds 

Exit to finder 

Mac Plus - 5.5 seconds Mac II - 1.5 seconds 

A partial list of software that currently bombs on the Mac II: 
MacTerminal 2.1, MacWrite 4.5, QUED 1.54, Videoworks, MS 
Works 1.0, MacDraft 1.2a, and (sob!) MacPlaymate. 

So as Bill says, it does run (some) software, and the speed is 
truly amazing (especially for computation intensive tasks like 
PackIt compression). 

Platinum Macs.... 

From: Scott Winders 

Well, My store got in 60 platinum Macs today!!! They look 
fantastic... Can you imagine having a platinum Mac, Ice white 
ImageWriter, and a beige disk drive??? Yuck.... 

Misc 

From: Macowaco 

Re: stuff on multiuser apps on Appletalk.....I can't imagine 
how anybody can even consider sharing app SW over dog slow 
Appletalk. It was NOT designed for that and therefore it will 
NOT perform for that. 

Anybody know of a lockup application that will work like 
Macserve's server? With Macserve's server I can create a non- 
network volume (only the server can get to it) with a password. 
The only way опе can get inside itand see what's in it (regardless 
of how the system is booted) is with the password. 

Finder 5.4 & Sys 3.3 on the XL 

From: mouseFur«tm» 

Using a Mac XL w/ 1 Meg RAM & MacWorks 3.0, I have 
found the Finder 5.4 compatible except when selected from 
SuperStation at which time it's a guaranteed crash. (1002) 
System 3.3 will NOT run at all. 

From: Rick Boarman 

I've been using System 3.3 & Finder 5.4 on an XL for a 
couple weeks now with no problems. The only quirk I can find 
is that the view by name choice is terribly slow. It takes ten or 
fifteen seconds to draw a small window. 

SYSTEM 3.3 

From: Jason G. 

I've noticed that while running under system 3.3/finder 5.4, 
the Mac seems to wantto do alot more disk swaps than under pre- 
vious systems (namely 3.2) Once booted up under the disk, if a 
file or disk copy, from another disk, is attempted, the Mac wants 
the system disk back; under 3.2, the copy occurs without any 
extra swaps. [Note: Apple wants everyone to use system 4.0 until 
4.] comes out in late spring. System 3.3 is only for Apple Share, 
whatever significance that has... (the word ‘everyone’ in Mac- 
Tutor means programming & technical types.) -Ed] 

International MAC, not true! 
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From: Jullo Carneiro 

I would like to raise a question I have not seen yet covered, 
regarding so called "International Macintosh", that interests all 
of us non US MAC users. Why, almost all (may be “ALL”) of 
the software written for the MAC does not use the information on 
the INTL resources for proper operation internationally. Some 
programs use it partially, like HELIX, which outputs dates 
according to INTL info (e.g. D/M/Y), but accepts only M/D/Y as 
input. Others, such as EXCEL, use a different, and private, 
resource for the month names table. The worst (eg OVERVUE) 
do not even allow you to use the foreign characters! Apple did 
a great job in the definition of the INTL resources, and associated 
packages. WHY NOT USE THEM?? The International Market 
should be taken into to account by the developers. Julio - from 
Brasil 

International Mac 

From: Mark Chally 

This may sound terrible, but frankly, the average American 
doesn't care much about the “outside world". Granted, s/he 
should, but s/he doesn't. Perhaps if Apple had not made it so easy 
to ignore such things as special characters it might be a little 
different. I mean, if you had to use special chars to get to 
regularly used items (like command-option being ctrl) then 
programmers wouldn't be so likely to ignore them. I know, 
because I'm one of those callous programmers who's in the 
process of getting rid of those characters in his program. I need 
atoggle-bit on my charactersfor separating chat characters from 
game commands in a game I' m writing, so the ol’ option-key got 
the axe. I’m sure if I'dlived in Brazil and felt I needed the special 
keys, I'd do it differently, but the temptation was too great. I 
don't have an answer except maybe the best thing you can do is 
write letters to magazines (this is an excellent place to complain 
with all the developers running around) and companies who 
offend. I hope I've helped enlighten you on . some of the 
possible reasons it may be done. If simply by laziness of 
LOOKING AT the option-key, that's BAD. I wish you luck and 
want you to know that I FEEL ABSOLUTELY TERRIBLE 
ТНАТ ГУЕ DONE IT TOO! 

Bug in AppleShare 

From: David W. 

While playing with AppleShare at a friendly dealer I found 
that dragging a copy of the system for an AppleShare folder to 
a floppy does not write the boot blocks on the floppy. 

From: Lsr 

This is not a bug. When you copy a system folder to a disk, 
the Finder initializes the boot blocks from the source disk. In the 
case of AppleShare however, the Finder cannot get the boot 
blocks from the server. The Appletalk Filing Protocol does not 
provide a way to get the boot block, since the server might not 
be a Macintosh. 

AppleShare 

From: Bob Denny 

I have been close to the AppleShare/TOPS thing and ... 
finally ...Ican talk about it. AppleShare represents a great deal 
(1 year) of intense work on the part of two terrific guys at Apple, 
Rich Brown and Pat Dirks. They took the original AFP spec that 
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was done as a team effort with Centram and ran with it. As they 
began to implement it, they discovered that theory and practice 
diverged. About the time they started, Centram and Apple had 
a "falling out" (details unimportant). Their cooperation ended. 
As development at Apple continued, Rich and Pat got into 
“imagining the possibilities” with respect to Finder enhance- 
ments. The result FINE piece of work! The only weak point 
that we can see is the net protocols used ... they're real hand- 
shakey ... bad news on internets with delays. 

Noisy Apple Stuff 

From: Bob Denny 

What is with Apple??? Haven't they figured out that “the 
rest of us" are sick and tired of noisy equipment? Our HD20-SC 
is so noisy that nobody will have it in their cube. The Mac П is 
also a noisy thing! 

System Heap Problems 

From: Bob Denny 

There is a bug in the 128K ROM where the system will crash 
inrandom “interesting” ways if system heap gets too full. Here 
is a LightSpeed C “program” that fixes this. You must build it 
as an INIT resource!! 


/* INIT resource to set the size of the System Heap to 56k 


*/ 
®include «MacTypes.h? 
®include <MemoryMgr .h»? 
define LargeHeapSize 0х0000ЕВ00 
mainC) 
( 
Handle Us; 
Se tApp 1Base( (long DLargeHeapSize); 
Us = RecoverHandle(*(Ptr *)0x9CE); /* Handle ourselves 
ЖҮ 
DisposHandle(CUs); /* Free memory containing us 
*/ а$т 
( 
тоуе.1 05,47 /* d? = handle (for macboot code) 
%/ 


) 
) 


WARNING!! Don'ttry to extend the system heap on the old 
Macs above $EBOO. The 64K ROMs have a brain-damaged trap 
dispatcher that was designed by the byte-squeaking pin-heads in 
the days when they thought no one would put more than 64K 
bytes RAM into the Mac. The dispatcher can't handle ROM 
Patches starting above the 64K line. Making the system heap 
larger than 56K pushes some patches that are in applications' 
heaps above that line and the system will bomb. Multiplan is a 
famous example of this. 

Quit to Finder 

From: The Atom 

I want to be able to make my Application re-run itself when 
ever ExitToShell is called. - so that an exit to the finder simply 
re-runs the application. Is it as easy as just changing the low- 
mem global that has the Finders name in it, or do I have to set 
something else special under HFS (blessed folders, etc.)? 
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From: Chief Wizard 

If youchange thelow-memory global to your application, an 
ExitToShell will re-run your application if it's in the Blessed 
Folder only. If it isn't in the Blessed Folder, you'll get an ID-26. 
(Or it may run the Finder, I’m not sure.) 

If you don't mind changing the environment (i.e., you're 
doing copy protection and don't mind if they have to reboot.), 
you can patch ExitToShell to a small routine of yours that you 


stick in the system heap that Launches your application again. 
Code Segments 
From: Lsr 


On the 128K ROM, if a code segment's rsrc attributes do not 
specify itas a locked resource, the Segment Loader will auto- 
magically call MoveHHi onit when loading itin. This avoids the 
problem of the 64K ROMs, where the Segment Loader would 
just lock a segment down wherever it happened to be (usually in 
the middle of the heap). 

You generally want segments at the top of the heap where 
they are out of the way, but you do need to be aware of this and 
allow for it in your memory management strategy. This is 
discussed in Tech Note #39. 

MPW Asm 

MPW Asm groups routines into PROCs and FUNCs. You 
can change the segment fora whole PROC or FUNC with a SEG 
directive before the PROC directive. If you specify a PROC as 
EXTERNAL, then its name will be external. All names within 
a PROC are internal unless you have an explicit EXTERNAL 
directive. 

MPW Disk Space Requirement 

From: Dennis C. De Mars 

I'dlike to take issue with the statement, that I have seen on 
this board and in MacTutor among other places, that you need a 
40MB drive to use MPW. Actually, MPW on a 20MB drive is 
quite comfortable; and Iam nottalking about a disk dedicated to 
MPW either. In fact, if you wanted to devote a hard disk to MPW, 
you could probably get by with a 10MB drive (buta 10MB drive 
is not cost-effective nowadays). 

Here are the raw statistics: I have MPW with assembler, 
MPW C, MPW Pascal and MacApp all resident on my 20 MB 
hard disk. Everything combined takes up less than 6MB, and that 
includes the compiled MacApp object module, as well as the 
complete MacApp source codes. Nothing has been deleted, in- 
cluding example files. I am working on two separate MacApp 
projects: together, they take up around 1.5MB, your mileage may 
vary. So you can see, it is an exaggeration to say that you need 
a 40MB drive. Now, if you already are pushing the 20MB limit 
without MPW, you obviously can’t fit MPW onto your disk. But 
if you get rid of garbage that you never access (save it all on 
floppies) you might be surprised. 

Apple Share... 

From: James B. Du Waldt 

Just got back from Mac Orange, where two men from Apple 
demoed AppleShare for us. Some notes follow : (1) To prevent 
only 1 copy of Excel, Word, etc. from being used by 25 people 
(apparently the largest number of users AppleShare will support 
AT ONCE), we now have 3 types of software: 
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File Server Unaware 
File Server Aware 
Network Ready 
Multiple Launch 
Multiple User 


MacWrite & MacPaint are “Server Unaware” - they can 
apparently foul up the works. Supposedly, if two people start 2 
copies of MacPaint while hooked up via AppleShare, there are 
conditions under which they can gain access to the others 
screen... “Server Aware” stuff is the vast majority of software. 
Basically, if two people try to run one copy, it won’t let them. 
"Network Ready" is the interesting category. “Multiple Launch” 
means just what it says - multiple people can launch Separate 
documents at the same time. Mike & Dave believe that most 
software companies will have versions of this sort for their 
bestsellers soon. Of course, it will cost “..just a dime more...”, 
as Mike jokingly said. 

"Multiple User" though, is the REAL winner. What this will 
do is allow two (or more) users to work on the SAME document, 
as long as they are working IN DIFFERENT PARTS of that 
document. The possible application Mike (sorry, I didn’t catch 
their last names) mentioned was two lawyers working on the 
same document. In fact, they said that one program coming out 
soon was for architects. The most interesting thing was how 
"Multiple User" programs would differentiate document areas, 
though. In the mainframe/mini world, users can do this by 
dividing their documents into fields orrecords. Apple Share will 
allow programmers & users to do it by "Byte Range Locking" - 

which right away sounds like a much more flexible scheme to 
me than records or fields ! (It immediately struck me as one of 
those “why didn't I think of it first” ideas - very fundamental!) 

And very fundamental to the Mac, too... bit-mapped ma- 
chine that itis. That means fields can be things like pictures, etc 
! 

Some good news for TOPS/MacServe/InBox users - Mike & 
Dave said that Appleis DEFINITELY cooperating with them in 
the production of new versions of their products. We apparently 
should be seeing them “soon” (scuttlebutt is this summer). 

For $700 (and a MANDITORY Network Administration 
training fee) you get a system that DOES need a dedicated Mac, 
allows 7 SCSI devices for up to a TOTAL of 660 MBytes, and 
allows 2 other drives to be connected to the drive port, AND will 
support as many workstations as you care to connect to the 
server. 

MS Basic Compiler comments 

From: Chris Riley 

Ihave been using the Microsoft Basic compiler (1.0) for the 
past couple of months. I have been using it to compile two 
programs for the most part: one is 22k source which compiles 
to 81k, and the other is 214.5k source which compiles to 420k. 

AS you can see, it produces quite large applications. Here is 
a list of problems and non-problems that I have found: 

Communications: I have seen several articles (including 
one in MacTuior) that claim that it doesn't work. We have been 
running a BBS (300/1200/2400) compiled with it for two months 
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and have had no problems with lost characters. However, we 
may be accessing the modem and reading characters in differ- 
ently than they do in the example terminal program. 

Clear statements: I have tried to resize the memory allocated 
forthe heap, stack, and data segment. Thiscompiles OK, but later 
several sections of code that access arrays do not work properly 
and return an Error #38 to the error trapping routine. I have 
removed the Clear statement and the problem disappears, so I 
know that it is the culprit. As of yet, there is “No Such Error" as 
a 38 listed in the manual, so I have no idea as to why this occurs. 

Error trapping: Errors are trapped fine, but the error line 
numbers are not returned in ERL properly (always says line #0). 
Without error trapping on, the correct line numbers are returned 
correctly, so I believe that there may be something wrong with 
the ERL statement. 

Bombs: ID 2 bombs occur too often with the compiled 
applications. It has also on two occasions bombed with an ID 3 
and an ID 10 bomb. Reallocating memory with the Clear 
statement seems to stop most of the ID 2 bombs from occurring 
(allocating more space for the stack), but as I stated above, they 
cause error 38s to appear in several places where arrays are 
accessed (but not all). 

Wish list: LPT1: In the manual it states that you can only 
open “LPT 1” for output. I do not know if it is possible to open 
it for input (haven't tried it), but it would be nice to be able to do 
SO. 

Application: A simple statement to allow you to respond to 
the "About application..." dialog and put your own information 
in there. (Perhaps allow the MENU statement to return 0 for the 
“About” in the Apple menu.) 

I would hope that Microsoft will release a fixed version of 
the compiler as it is much better than ZBasic for compiling MS 
Basic code. With its bugs fixed it would be excellent. 

Compiler update 

From: Dave Kelly 

I received a new version of PCMacBasic a few days ago. 
Looks like they have started work on it again. I wrote MS a letter 
will full set of complaints about their compiler, and they have 
invited Dave Smith and myself to come up and discuss future 
product development. 

New Tecmar s/w (HFS) 

From: Vax Hack 

I've been bugging Tecmar for new HFS compatible s/w for 
the MacDrive. Yesterday, they called to announce version 2.3 for 
only $50 + $3 s/h. While I'm very happy to get it, I can't help 
thinking what $50 will buy in terms of Mac s/w and how many 
s/w updates are FREE or MAYBE $10. And why should I start 
to expect decent after sale service for my MacDrive at this late 
date? 

Jasmine DD 20 

From: David Robinson 

I would also like to agree with all those who posted above in 
support of the Jasmine Direct Drive 20. We have 2 of them and 
love em! This drive is very fast and incredible quiet. The surge 
protected outlets and external SCSI address switch are just two 
of the great features of this drive. Other features include; Filtered 
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air intake, low profile & small footprint, easy access to terminat- 
ing resistors to allow chaining of drives without opening the 
case, cable included, 1 year rep. wrty. , 48 hour turn around on 
repaires , external access to fuse. What else do ya want for 
$612.72 delivered to your door. Go buy one now and help 
support this company that has made high quality affordable 
drives available to the rest of use. I'm excited, can you tell? 

From: Jim Reekes 

The Jasmine is pretty much the same drive as the Apple 
20SC. They both use a noisy Seagate 225N. I suspect the per- 
formance is about the same too. Don't get too excited about the 
PD stuff they install on it, most of it is trite. The Jasmine doesn't 
require you to buy a terminator and has some handy power 
outlets too. I can’t tell you how long they'll be around to service 
it, and I don’t think you can get enough hard disk support over 
the phone. The question you should ask yourself is “will it still 
work in six months, and what if it don’t?” Hard disk have a 
tendency to develop bad tracks after so much use. 

I don’t like the idea that they _only_ sell mail order and not 
to dealers. [remember the Sider situation?] The only other 
difference between Apple’s and Jasmine’s is the price. The 
20SC is way over priced, and the Jasmine isn’t. Consider this, 
if you could successfully complete the MacTutor’s “build your 
own hard disk” project, then you should buy a Jasmine. The parts 
would cost you about the same. 

I couldn’t recommend sending away your money until you 
seen, heard, and had the chance to use it. Also, one thing to make 
note of. The Mac Plus’ SCSI software is going to change real 
soon [there is a ROM update coming out]. I know that many 
drives will not be ready for this. Stick with a name brand hard 
disk. And make sure you geta backup system for what ever drive 


you get. Don’t drive without a backup, you’ll kill yourself! 
DiskTimer Il, etc. 


From: Mac Spy 

Iran DiskTimer II on the Paris with its internal 40 meg drive. 
The results: Reads - 36; Writes - 42; Seeks - 15. 

The HD 80 on a Mac+: Reads - 67; Writes - 67; Seeks - 

18. Thats the Apple HD 80.... 

Disk First Aid Workings 

From: Phil Kutzenco 

If you type command S just before telling Disk First Aid to 
start ех- amining a volume it will open a window and tell you 
what it is doing. As it examines the disk it checks: 

disk volume 

extent BTree 

extent file 

catalog BTree 

catalog file 

catalog heirarchy 

volume info 

Idon't know what kind of problems it can repair, but I have 
adisk with a problem that makes Disk First Aid terminate while 
checking the catalog BTree andit just says itcan’t verify the disk. 
It doesn’t offer to repair the damage. 

APPLE MENU QUESTION 
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From: Ram Warrior 

I'm writing an application in turbo pascal and I need help 
with the Apple menu. I’ve got the program handling DA’s fine 
but if the menu has to scroll, the menu items get mashed together. 

From: Rick Boarman 

If you have any Icons in the Apple menu, it causes it to get 
all scrunched up when scrolled. Without the Icon itshould work 
fine if you use System 3.2 and Finder 5.3. 

From: Laser Dolphin 

Itseems any menu with icons in it will mess up the scrolling 
royally. This is a pretty severe bug in the new menu manager.... 
Sigh.... 

Multiple regions 

From: Jack Howarth 

I'm trying to use an array of region handles to record the 
regions that different data sets contain when plotted in a 
GrafPort. WhatIam not certain about is how to handle more than 
one region at a time. I am currently creating the rgnhandles with 
NewRgn and then OpenRgn to use it. What I want to do is 
repeatedly come back to existing regions and add to their 
contents. I know I can stop collecting to a region by saving the 
rgnSave field and substituting NIL. However, is rgnSave the 
same as the rgnHandle for that region? Also, must I close the rgn 
before I open another? If not, I would think I could open any 
number of regions, NIL the rgnSave and reactivate the regions 
by substituting their rgnhandle into rgnSave. Lastly, does 
OpenRgn destroy the current data in that region or just append 
it onto the existing stuff? 

Multiple Regions 

From: Rick Boarman 

Jack, Youmustclose aregion before using another one. If 
you don't the old region would get written over or just appended 
onto. Be sure to close the region before calling NewRgn again. 
Also be sure you are storing the handles in different variables. 

Text Handling 


From: Micro Ghoul 

Ciao, Ihave been (for that last 6 months) working with the 
Core Edit text handling tool from Apple (this was originally 
made for the Lisa Development system and I am not too pleased 
with it at this time), and have a few questions to the general 
peoples out there. 

l. Is anyone out there using a licensable text handling tool 
that can either do or does not make unfairly difficult: 

* display text in multiple styles, sizes, & fonts * left, right, 
center, full justification * tabbing * first line indentation * 
insertion of char(s) * translates mouse activity into text selection 
* Cut, Copy, Paste * word wrap 

2. Has anyone used the newer version of Core Edit from 
Encore Systems? 

3. Does anyone know their phone # as they never answer 
their AppleLink mail? 

4. Are most of you using TextEdit? 

5. Those that need extended abilities are you developing 
your own from scratch? 

6. Anyone want to comment on their experiences with the 
handling of text on the Macintosh? (I know that if people are 
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interested in the topic I am more than willing to discuss the 
problems that I came up against). 

From: Jeff | 

Isn't Core Edit fun? I also used (wrestled with) Core Edit on 
the Lisa for a couple months before deciding to start from 
scratch. Apart from its bugs, Core Edit's biggest limitation is that 
it seems to provide no way to do page breaks, and as you may 
have noticed it isn't exactly speedy. At one time we did get a 
version of the documentation of core edit which had routines to 
support page breaks and a couple of other goodies. The source 
code we got, didn't have those routines accessible, although 
there seemed to be some remnants. Finally we decided that it 
would probably be a heck of a lot faster to start from scratch than 
to try and rescue someone else's soggy, ancient code (Core Edit 
was written in 82 I think? - back in the old days before the 
computer for the rest of us) 

Writing the equivalent of core edit including page breaks, 
and other goodies took a month or two. Also writing your own 
routines allows you to take full advantage of the 128 ROMs 
improved font manager features such as fractional character 
spacing and intelligent font scaling. Fractional character spacing 
helps in increasing accuracy when printing to the LaserWriter 
and font scaling helps makes it so that when a font is not available 
it doesn't just use copybits to scale an existing font but instead 
will take a smaller font but leave larger space around the char- 
acter. This enables you to edit in real time (which is always nice). 
Hopefully the new 256K ROM may even have more goodies in 
Store for us. 

From: Chief Wizard 

Ihave to agree with Jeff - stay away from Core Edit. For the 
amount of effort it will take you to develop your own font/style 
changes in TextEdit, you'll save yourself some large headaches. 

Trap Calls for Time Manager . 

From: Sticks 

Iam trying to program amillisecond timer for the Mac using 
the time-manager calls as listed in inside Macintosh Vol.4 pages 
300-301. The routines are: InsTime, PrimeTime and RmvTime. 
My Aztec C 1.06H.1 does not include these calls in its header 
files. When I attempted to write my own header I found that the 
Trap Words are not listed in Inside Mac Volume 4 page 305. 
Doesanyone know the Trap Numbers. Can anyone give meany 
info. on these routines? 

From: Rick Boarman 

The Trap words you need are: 

_InsTime $A058 

_PrimeTime $A05A 

_RmvTime $A059 

I found them with TMON on a Mac +. 


The Great MouseHole 
Pirate software survey... 

How many programs do you USE (as oppose to just having 
them on disk stored in a drawer or something) that you haven’t 
bought or obtained legally? 

Total Votes: 203 

1.28% (None) 2.33% (One or Two) 

3.19% (Three to Six) 4.18% (Seven or More!) 
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Fax communication 

From: Mysteray 4432 

Some months ago there was some stuff here about making 
the Mac into a FAX machine. For those interested (in what a 
slotted machine can do), the current issue of EDN has a special 
article on FAX cards designed for the ibm-pc [intentional lc]. 
They seem to be around $1000. They offer special compression 
techniques and error correction. There is even a product that can 
allow simultaneous editing by parties on both ends, with the 
resultant graphical output file identical on both ends. Very 
interesting reading for anyone interested in communications & 
graphics. 

Might we see similar products for the Mac II within the next 
9-12 months? I would noy bet against it, for sure. Now WE can 
begin to flex our muscles and move into the slotted world. 

Finder bug 

From: Mysteray #432 

I just found a strange bug in Finder 5.3 that may provoke 
thought... 

1. I grouped three files from my Ram Disk (Ram Start 1.21). 
These were small MacDraw & MacWrite docs. 

2. I dragged these to a floppy disk icon, my target. 

3. A dialog box came up, approx: "not enuf memory to do 
copy; ungroup and drag one-by-one" 

4. I did just that, but 2 (of 3) reportedly were already copied, 
but I clicked to replace anyway, feeling suspicious. The 3rd 
reportedly couldn't be copied because it was "locked or in use" 
(but in fact wasn't). (Too bad I didn't have a zap DA in the system 
this time.) Also: the finder reported that the copies were of the 
right size. 

5. I ejected my target disk (by dragging the disk icon into 
trash). Then I re-inserted it. IT CAME BACK WITHOUT 
THOSE NEW FILES. And the one still in Ram Disk now was no 
longer "locked or in use". 

6. I then dragged ‘em individually, with no problems. 

I'm now going to upgrade to the new Bloating-Trashcan 
Finder in hopes that strange things like this have been fixed. (And 
maybe other strange bombs too.) [This sounds very much like a 
RAM disk problem and not a Finder problem. -Ed] 

What: Forth 

From: Tim Hewitt #150 

I am a Forth programmer, converting to C for my new job, 
buta Forth programmer at heart. On the Mac, there is really only 
one Forth, and that is MacForth Plus. It is a very mature, almost 
bug free product with tremendous developer support and a 
terrific track record. The folks at PAS have done a very good job 
with Mach 2, but it has yet to produce a completed serious Mac 
application, and it is still a product in infancy. 

A partial list of products developed in MacForth includes, 
Back to Basic Accounting, Chipwitts, MacGDS (professional 
CAD), Easy 3D, Pro-3D, Total Music, StudioMac, Digibase, 
PosteHaste, Mac Lion, MARS 2, Pro-Mac. All of these are off 
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the top of my head. 

The support mechanism CSI has set up on Compuserve is 
superb, and the development environment MacForth Plus pres- 
ents to the programmer rivals anything available for any micro. 
I have been working in MacForth for almost three years, and 
really feel like I am stepping back into the stone age program- 
ming in LightSpeed C. I abandoned Mach 2 after not being able 
to successfully compile and run a major application, in an very 
immature environment. 

What: Upgrade Paths 

From: Zenomorph #353 

I've been inside both new Macintoshs. There is no way in 
heaven you can expect an upgrade to Macintosh SE from Apple. 
The SE is a total rewrite of everything in the plus, new Logic 
board, new case, new spaceframe, new power supply, and new 
front cover. 

The one suggestion I can make is to pay off your Macintosh 
and use it or sellit cheap (why cheap? beacuse everybody knows 
computers don't retain one 1/5 of their value after two years!) and 
wait until next march to buy a new Macintosh. The prices will 
have dropped and they will have lots of new software justifing 
a purchase. I'm sorry if you didn't want to hear this but look at the 
facts. 

What: SE Surprise 

From: Scott Winders #465 

If you have a Macintosh SE, hit your interupt switch and 
type in the following: G 41D89A. Sit back and watch the show! 
And you wanted to know what they did with that extra ROM 
space... 

What: FullWrite Pro Beta... 

From: Jon Magill #382 

FulIWrite Professional just gave a demo last Friday and said 
that they would be sending out Beta's to test sites by the end of the 
month. They also indicated that the product would be shipping 
in 60 to 90 days. Itis one of the hottest s/w products I have seen. 
My notes from the demo include things that impressed me like: 
side bars, change bars, dynamic references, linkable renumber- 
ing documents, auto indexes and tables of contents, find window 
has its own menus, strikeouts, of course flow around irregular 
objects, own drawing environment, mixed size multi columns on 
one page, tiled windows with linked updates between them, 
sophisticated searches and replacements, lots of other goodies 
and all very simple to use and Mac-like (unlike that other word 
processor from Microsoft) no they didn't replace the mouse with 
keys on this package. Price will still be $295. 

What:Disk Interleaving on new Mac's 

From: Zenomorph #353 

Well gang I went out yesterday and sat down in front of a 
Mac Plus, SE, II and I tried formatting a disk on each of the new 
machines. I then placed the disk into the Plus's disk drive. I 
booted the Plus and opened Word 1.05 Remember I formatted 
this 800k disk on a Mac II with a 1 to 1 sector interleaf. The boot 
difference was no more than 10 percent. Word 1.05 opened up 
in 24 seconds without the cache on. 

I reformatted the same disk on the Macintosh Plus and then 
placed it into the Mac II after moving Word 1.05 to the disk. 


© The Essential MacTutor, Vol. 3 


Word 1.05 opened up in 14 seconds. My conclusion is that the 
Interleaf variation between machines is not a problem. 

What: TurboMax 

From: Max #406 

Just received a "pre-release" version of Mac Memory's 
TurboMax upgrade for the Mac Plus and 512e. Includes a 
separate board, with a 68000, 2-megs of RAM, a 16 Mhz clock, 
and a 68881 co-processor. Features a separate power supply, a 
fan, a high-speed SCSI port, will accept a 40-meg internal hard 
drive, has an output for a (future) big screen card, and will expand 
to 4-megs. 

The speed increase is AMAZING... and no software incom- 
patibility (MS Works, MS Excel, MS Word 3.0, Jazz, 
SuperPaint, RedRyder 10.0, MacDraft 1.2a). Thus far, it's 
running fine under System 4.0/Finder 5.4. I will soon run bench- 
tests against a stock Mac Plus, and a Levco Prodigy-4 enhanced 
Mac. This might be a really good product: Retail price (without 
68881 and internal hard drive) is only $1300+install. 

Anybody else out there running a similar pre-release test for 
Mac Memory? I'd be interested in any feedback (E-mail or 
whatever) anyone has on this piece. 

What: Mc Face 

From: Blacksmith #540 

Dan Kampmeier (the developer of Mc Face) is probably the 
most helpful and accessable (developer) I have had a chance to 
speak to. 

About Mc Face. This isreally anice piece of code. Basically 
it provides a very credable Macintosh interface without forcing 
the Fortran programmer to learn any of the toolbox calls. No fun 
if you аге a dedicated Mac Hacker but great if you just want to get 
your Fortran stuff working quickly on the Mac. If you have your 
heart set on getting into the toolbox he will sell you the source 
code for a reasonable price. If you are writing Fortran on the Mac 
I think this is a steal! 

What: System 4.0 

From: Rick Boarman #377 

Гуе been using System 4.0 since mid Feb with no problems 
whatsoever. I have it on a Mac+ with a ProApp 40S and on a 
MacXL. Word 3.0 runs fine along with every other application 
I've tried. I would suggest that anyone who likes the features of 
the new System/Finder combination to go ahead and use it. Just 
be sure to have some backups around. 

From: Kerry #102 

We have been running Finder 5.4 and System 4.0 for awhile 
now. If something is going to bomb it will bomb on our system. 
We have 4 Macs and an IBM running TOPS, Intermail, Super- 
LaserSpool, usually a Network game each day, every Mac has a 
different hardware configuration (i.e. RAM, hard drives, etc.). 
The new system works fine for us except for running NetTrek 
from a hard drive. We have to boot up a floppy (we use the new 
system) and run NetTrek from a disk. 

From: Jim Reekes #583 

On a Mac+ it loads mucho data into the system heap. If 
you're gonna run a program that hogs memory, then you're in 
trouble. Boot up w/4.0 and run Omnis III+, a spectacular bomb. 
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The universal installer scripts are not ready yet. If anyone is 
running an AppleTalk net, then every Mac must run the same 
system version. If you're using Switcher, or similar util, don't use 
4.0 on your Мас+. Generally, if you have a SE, or are using 4.0, 
your a beta tester. [Maybe but I've used Omnis Ш+ with 4.0 
without any problems. I think your being a little pesimistic. -Ed] 

From: Mark Chally #561 

I've been using 4.0 on my Jasmine for a couple weeks now, 
and on an HD20 for a couple days before that...it works without 
a hitch. (my copy was the Jan 15 version). I think it's great. 

On interleaving...my Jasmine is set up at 2-to-1...so is a 
friends. The earlier software he had was for 3-to-1...neither one 
seems to have any problems...oh, by the way, the Jasmine is 
REAL fast--hard to beleive they're using a Seagate 225 (ick) in 
there--Iget 106, 107, and 36 on DiskTimer I..that's about 250kb/ 
sec read/write and 45ms seek over 1mb! 

MPW Pascal & Macintalk 

From: Jaff 4314 

MPW Pascal seems to have omitted interface and objects 
for the talking Mac. Anyone have a solution? I builtan interface 
file, tried to convert my TML Speech.rel, but no success in 
linking. Help! 

From: Cpettus #484 

APDA sells a new(er) version of the MacInTalk Develop- 
ment package which includes MPW bindings for the driver. It 
ISN'T perfect (with MPW 1.0, it required a bit of editing before 
it would compile correctly), but it works when twiddled with... 

MPW Help 

From: Power Hopeful #323 

I need some expert advice... I can't seem to get the exact 
syntax of an IMPORT statement in MPW assembler. 

I want to import either a specific template definition, or a 
module containing many RECORD templates. I'd be most 
appreciative of anyone's time in helping! 

From: Jim Reekes #583 


PH, try this in the main file: 
TheRecord RECORD EXPORT 
fieldl DS 
field2 DS 

ENDR 
and then this in the seperate file: 
TheRecord RECORD IMPORT 
field! DS 
field2 DS 

ENDR 


But, don't use the 0” after the record statement unless you 
really know what it means. Templates cannot be IMPORTed, 
you should make a file of template definitions and then include 
it at assembly time. If you use the ‘0’, then that record is really a 
list of offsets based on the location counter. No data structures 
will be generated. If you use the EXPORT option, then data will 
be generated. So data structures can be EXPORTED to other 
files, but templates cannot. 

_Datainit? 

From: Power Hopeful #323 

Is anyone aware of a bug in _Datainit? In calling it I'm 


569 


е 


getting an illegal error. If. datainit is not the culprit, can anyone 
possibly suggest why the code directly following it seems no- 
where to be found? After calling it, it's necessary to IMPORT 
some other stuff, and these import statements seem to be prevent- 
ing the asm instructions from appearing anywhere. I know I'm 
not explaining the problem in detail here, but if anyone has a 
general solution to this general description, it would be VERY 
helpful. If not, I guess I'll burden you later with the gorry and 
boring details 

From: Jim Reekes #583 

When: 8:12a Mon, 16-Mar-87 

Create a segment strickly for initialization purposes. First 
line of this seg should be "JSR . DatalInit". Then init all the rest 
of the managers and so forth. RTS back to your MAIN code, and 
then " UnLoadSeg" on that initialization code. Make sure that 
you include the RunTime.o during the link process. 

From: Power Hopeful #323 

Most of my problems have to do with the placement of the 
data within the module(s). Actually, I've had no luck importing 
declared data to the main mod and have thus simply compressed 
it all into one MAIN. Is there a simple rule governing ‘data’ 
statements (i.e., those statements declared as DATA) within the 
module? It's whenI've solabelled my data that the problems arise 
with both the structure of the final object code and with _datainit. 
Further, this data declaration seems to be required at the begin- 
ning of the program. 

Lately I've just been arranging the program like those in 
MDS with the data statements unlabelled at the end and have had 
no real problem. Maybe in a nutshell you could tell me just what 
the advantages of the IMPORT facility are....besides the prob- 
lems I've had trying to use it, I really can't see -- since each and 
every locally referred-to variable and constant must be explicitly 
declared IMPORTED -- what the point of defining data else- 
where is. 

From: Jim Reekes #583 

There's no simple rule to follow for declaring data struc- 
tures, because there are many complex data sets and many 
methods of programming with MPW. But basically, you only 
need to define data once in a file then import it into other files. If 
you're going to import data into more than one procedure, then 
make it global to the entire file. Your problem is probably that 
the MPW Linker is looking for P-code, and you're writing 68000. 

Remember that the Mac ROMS use Pascal data structures, 
so you might as well get used to RECORDS. If your program is 
complex and uses many separate source files, then you're gonna 
need to import some data and code. Importing will save you from 
unnecessary coding. Records will help to document your pro- 
gram. [complete docs are a must in assembler]. Records will let 
you use symbol names instead of offsets. 

You mentioned that you are trying to write all of your 
program in one main source like in MDS. Do you mean ‘one main 
code segment or "опе source file’. Big difference. MPW will let 
you place your source code into different code segments. Unless 
your writing more than 32k of code, you won't need more than a 
'MAIN' code segment. But, if you trying to write all that code in 
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one file, you're working too hard. Seperate files allows for 
shorter Asm/Link times and ease of matenance. Also, try to write 
'object oriented' code and you'll need less imported data. The 
reason for importing data structures is to allow seperate files to 
use the same data. Importing will also better document your code 
by re-defining the data you'll be using. 

I put all of my initialization code into a 'INIT' segment and 
unload it right before my event loop. [No need to keep it around.] 
All the rest will be place into the 'MAIN' segment. I still don't 
think that. DataInit is the root of your troubles. It only requires 
about 4 lines of code and can otherwise be ignored. The reason 
for importing data structures is to allow seperate files to use the 
same data stored in RAM during run-time. 

Monkey see... 

From: Bill Evans #508 

In :aincludes:sysequ.a which comes with MPW, there's a 
cute little line at about line 130 or line 140: 

MonkeyLives EQU $100 ; monkey lives if >= Ø [ word] 

Anybody have any idea what it's for? I hate to monkey with 
It. 

[MonkeyLives is a trap that goes back to the early days of 
the Macintosh. It was described by Andy Hertzfeld at a Mac 
seminar once. If MonkeyLives is not zero then random events are 
posted to the system that can be used to implement via a hook, a 
process that only runs when the monkey event is generated. 
Apparently it was implemented once by Andy or someone back 
in the Steve Jobs era in such a way that at random intervals, when 
a menu was pulled down, instead of a menu list, a PICT of a 
person was displayed instead. When the menu was pulled down 
again, the list returned! This led to a story that Jobs claimed there 
was a monkey in his Mac but when he showed anyone, it wasn't 
there. MacTutor would love to have a demonstration of monkey 
events! -Ed] 

From: The Atom #397 

Remember apple's monkey DA? That's what the global 
MonkeyLives is for. When you run the da, it moves the pointer 
around the screen and generates random events, in order to test 
out your application. You can put in checks for monkey lives(the 
da is running if>0), so that you disable functions like quitting, 
writing something to disk, or other potentially dangerous func- 
tions while debugging. That way when you run the Monkey DA, 
your program won't try to save out files or something if you have 
the correct checks in. 

Where's the beef? 

From: Jim Reekes #583 

After playing with an SE all day, I really didn't see any faster 
speed. Although things like consectutive block reads were good, 
I see the same overall speeds on the Mac+. An Excel macro 
actually ran faster on the Plus. The gray color next to beige is 
enough to make you puke. The horz slots on the front, and vert 
ones around the side make it look real computer-like. I can 
foresee problems with the internal 20. 

First of all, it's a Rodime. [blech] I think it's too fragile to 
transport. It is lucky enough to have a 50 pin cable to the mother 
board. I suggest people with drives having 50 pins to mount a 
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centronic 50 out the rear of the SE, and connect internally. [about 
$6 worth of parts] Incidently, the new Sony power supply is 
beefier but it looked like all the video components were the same 
as the old one. [which is what usually failed] If you remove the 
logic board, the speaker wire will make you curse trying to 
replace it. I like the new keyboards. When do we get the 1.6Mb 
floppies? What happens if parameter RAM is completely 
scrambled? You can't pull the battery out, so we need a new util 
to zero it out. 

Ill wait for a Mac II, in 1988. Yup, I'll wait till next year. 

New ROMs for Mac Plus 

From: Mac Spy 4477 

Apple will NOT sell the new ROMs that are being shipped 
in the new Mac Plus. Oh Well.. [These ROMS reportedly have 
the SCSI fixes in them, some of which may be not be available 
from System File patches. The only solution appears to be a 
friendly dealer who will swap for you. -Ed] 

Mac ll to Sony Multi-sync 

From: Chief Wizard #123 

Lots of people have complained about the high cost of 
Apple's new color monitor for the Mac II. Here are the pinout for 
a Mac II to Sony Multi-Scan mointor (it looks HOT!) 

Mac li (DB-15) Sony (DB-9) 
1 


1 Gnd 
2 3 Red 
5 4 Green w/Sync 
9 5 Blue 


Use a shielded cable, and tie the sheild to pins 4 and 2 (Mac 
& Sony, respectively.) Unfortunately, the NEC won't work 
without a modification to the video card. The video card uses a 
67 Hz vertical frequency, and the NEC only goes up to 62 Hz. The 
Sony can handle 50 - 100 Hz. 

On the good side, though, there are people all over the place 
selling the Sony Multi-Scan (Part # CPD-1302) for less than 


$600. 
. Disk First Aid 

From: Dr. Dog 4295 

Ihad the same problem with Disk First Aide as Jim Reekes. 
Everytime it ran the "Death" icon appeared over the various 
options in the iconic menu. I knew there was a problem too, 
because I would occasionally write to a bad sector and couldn't 
open that file. The interim solution was to keep the disk only full 
to 12 of 20 megs, so that that sector wouldn't be used. I finally 
located the bad sector by paging through the upper sectors of the 
disk with FEDIT. I found a sector (#38942) on the HD 20 that 
FEDIT couldn't open to read--that bad sector! By choosing write 
extended from the FEDIT menu, I could read the bad sector (and 
write it). It turned out that the tags were bad. The file number tag 
was F0783C1E (-260555746)! Naturally, that was absurd and 
the reason why Disk Express was confused--it couldn't reconcile 
the disk directory's contents with the file number attached to this 
sector. I just wiped out the tags, all data in the sector, and 
reformatted the disk. It now works perfectly, Disk Express runs 
fine, and that particular sector can have data written to it and read 
from it with no problem. So, I suspect Disk First Aide does not 
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deal with the tags in the repair mode. It certaintly didn't correct 
the outrageous file number on my bad sector. Instead, it just 
blindly compares the.directory with known sector tags and says 
"its bad." 
From: James B. Du Waldt 4322 

It's rather ironic that the tags caused the problem; accord- 
ing to a recent Mac Tech Note, tag use is being discontinued 
because it wasn't found to be effective in assisting in rebuilding 
trashed files. Hmmm... reminds me of a story afew years back... 
Eagle Computers (remember them ?) came out with a business 
PC that didn't have parity checking on the memory, ala Immense 
BM. The reason why was because Eagle engineers did some 
research and decided that the increased number of RAMS re- 
quired LOWERED reliability, not raised it... Eagle had a good 
reputation for quality (but their docs were supposed to be TER- 
RIBLE), and when was the last time you had a parity error on your 
Mac...? 

SCSI Drives and SE 

From: Sam #261 

If you are using a SCSI drive with an SE or Mac II that was 
not shipped with your new Apple and are having strange things 
happen like boot failure or disappearing volumes (from. the 
Finder, that is) try using the latest SCSI Setup program from 
Apple on your drive. Select the UPDATE option (it doesn't write 
over any user data) to install the new SCSI driver. That should 
fix the above problems if there is nothing physically wrong with 
the drive. 

From: Scott Winders #465 

Sam, why in the world would you try to put Apple's SCSI 
driver on someone elses hard disk?? It would only work if they 
have the same drive and controller and the same ROM on that 
controller. Do what you suggest to a DataFrame and nothing 
would happen anyway. 

From: Sam #261 

Ok, let me be a bit more specific... if you are using a Seagate 
ST255N as found in Apple drives, Jasmine, and a host of others 
or the Rodime equivalent of the Seagate, and are having boot 
problems try the Apple program first. 

From: The Anarchist #103 

I am using a dataframe XP 20 on my SE. It works fine, but 
it was formatted and inited with the 2.3 util. I am assuming that 
the 2.2 formatter did have problems. (The new formatter is 
necessary to re-format the boot blocks with a new SCSI driver. 
Then it works fine with the SE and II. -Ed] 

From: Power Hopeful #323 

I was attempting to use a dataframe XP 40 on my mac plus 
with a 68020...init 2.1 was absolutely useless, and I was told 2.2 
would remedy address problems, but that turned out not to be 
precisely the case. Ihad alotof problems with that processor and 
finally removed it. 

By the way, when I first put all my software on the hard disk, 
it registered about 20 meg with 20 meg available. I patiently 
waited through Disk Express, and was richly rewarded by the 
information that I then had about 7 meg on the HD, with 33 meg 
available! 


571 


Chilton Book 
From: Macowaco #222 
Of all companies to do it....Chilton has just published a 
maintainance manual and fixit giude for the Mac. I was about to 
buy it but I don'texpectto need it very much longer since it doesnt 
cover the II. 
Memory Upgrades 
From: Arnold Woodworth #296 
I want to upgrade my 512K Mac to 2 Meg. I know some of 
you folks have experience with upgrades. Can you tell me about 
them? Who's good? Who's bad? I'm considering Micrographic 
Images or Levco. 
From: Rick Boarman #377 
Arnold, Stay away from MicroGraphic Images. We have 
had a 100% failure rate with their MegaScreen. Every single unit 
we have sold has had to be worked on. The last repair was over 
$300.00. Levco and Dove have very clean memory upgrades. 
I would suggest getting a Mac- upgrade and then going to 
20r4 meg. The 512 motherboard just wasn't designed for larger 
memory configurations. 
EasyDrives 
From: SpUd PoTatO #449 
The new EasyDrives now have Fujitsu Drives in them, 
replacing the Seagate 225N. As a result, access time is quicker, 
the drive it quieter, and their prices have dropped $200! 30MB 
SCSI drive for only $649! Not bad, eh? 
lightspeed c 
From: Dirck 4188 
I wanted to say that I received lightspeed c v2.01 in the mail 
unsolicited and no charge for the upgrade. That shows real class 
(after paying for at least 2 TML upgrades). Anyway, they fixed 
one of the bugs in fseek, but not the other one, even though the 
code looks like it's been rewritten. (I use lightspeed for develop- 
ing code for other machines). There's a coupla missing brackets 
in their fseek. Anyway, I ran into another bug last night. Try this 
out: 
esn ( 
move SR, а0 
move 00,58 
move dO, CCR 
move CCR, dd 
) 
wild, huh? Time to do some selective hand assembly. 
MacApp and TML 
From: Worker #526 
I think the segment difference is in the use (by MPW) of 
segment aliases, which could be overcome without a new linker, 
but with some hassle. The changes I made to MDS weren't 
necessary, as MDS is not needed - the MacApp assembler 
sources are low-level stuff thatexists in TML in another form. An 
obstacle that cannot be overcome (to my satisfaction) is that 
MacApp requires the availability of function and procedure 
parameters, which TML lacks (why do Pascal compiler makers 
always leave this one out? It's as if they were only interested in 
what my data structures professor called the FORTRAN subset 
of Pascal'!). I think I will call him. 
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MacApp DA Newsletter 

From: Lsr #309 

I just got the second issue of the MacApp Developers 
Association newsletter. It contains a summary of the MacApp 
DA meeting that was held in SF during MacWorld, some added 
info about the group, an example UNIT that handles the serial 
port, and interviews with Tom Leonard (TML) and Dave Inter- 
simone (Borland). The Borland interview was pretty interesting; 
MacApp support is definitely on their list of enhancements, but 
probably not for release 2. (There is also an interesting story of 
Phillippe Kahn and MacApp.) 

Illustrator files in Word3.0 

From: Greg Kearney #364 

Ok someone was asking how Word 3.0 reads Illustrator 
files, well here is a simple (I hope ) explanation: 

First the file must be in EPSF format. This format saves both 
a bitmap representation of the file , what you would see in the 
Preview mode and a PostScript description that will be sent to the 
printer (think of it like a downloading font only its a picture.) 

Next when you place an Illustrator file into word, you see 
the bitmap on the screen but when you print, the driver goes out 
to the file and downloads the PostScript to the printer when it 
encounters that object in the PS stack so that what you get is better 
than what you see. 

As an after thought Cricket Draw does a similer thing with 
its PICT files only it puts the PostScript into the comment field 
of the file so the printing program does not need to go out to the 
disk to get it. 

Igota copy of EPress that prints!!! and is it something! you 
should see whole newspaper pages coming out of the Linotype 
500 from a MAC! 

SE ROMS in a Plus? 

From: Jim Reekes #583 

The ROMs in the Mac SE will NOT work in a Plus. The new SE 
ROMS have a different pin out than the Plus ROMs. If you plug 
them into the Plus mother board or a EPROM reader, you will 
mostly likely burn up the chips. the power line is not on the same 
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LaserPrep revisited... 

From: Richard Clark 

In a post here a few months ago, I mentioned how typing 
«Command-K» while printing to the LaserWriter gives you a 
text copy of the LaserPrep file. (Just like «Command-F» gives 
you the PostScript commands for the document you otherwise 
would be printing.) Unfortunately, just downloading the Prep file 
* the PS file doesn't work right — everything comes out in 
Courier. Well, I just found out what's happening: 

The LaserWriter needs to have its internal "font list" initial- 
ized first. Try the following (after LaserPrep and before the PS 
file): 


$ The query 
md begin 
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B?fontList 
Isf 

%?end 

end 


Or, you can initialize just the fonts you need: 


% make this “semi-permanent”, i.e. until the power goes off 

$ Cotherwise, it only applies for this job) 

serverdict begin 0 exitserver 

md begin 

% The format is... 

%/<Coordinated-name> 
ing?) rf 

/|_Times-Roman /Times-Roman T rf 

% Use the built-in encoding vector for the above. 

% Most of the fonts are of the above form (i.e. Times-Bold, 

% Times-Oblique, etc.) but there are 2 exceptions: 

/|__Symbo1 /Symbol F rf 

% Use the LaserWriter’s encoding vector for Symbol С?) 

% Zapf dingbats is a special case - we^11 have to def ine some 

% encodings ourselves 

/|_ZapfDingbats /ZapfDingbats du fe 

% redefine the encoding vector... 

% format is: «encoding-position? <name> «орегапа» 

128 /a89 ce 

129 /a90 ce 

130 /a93 ce 

131 /894 ce 

132 /a91 ce 

133 /a92 ce 

134 /a205 ce 

135 /а85 ce 

136 /a206 ce 

137 /a86 ce 

138 /a87 ce 

139 /а88 ce 

140 /a95 ce 

141 /896 ce 

nf 


/<Previous-name> <Use-built-in-encod- 


AppleLink users can get the whole story by searching the 
"Service" library for “LaserWriter” and then looking at “Work- 
ing with LaserPrep and PostScript files”. 


Animation on new machines? 

From: Roy Hashimoto 

Do the new machines (particularly the IT) support multiple 
selectable video pages? I realize that in the II, the display 
memory is on the video card (at least that's what I think), but if 
you are working in 1- or 2-bit mode, is the additional memory 
available to your process, and can it be displayed as a second 
page? 

Furthermore, is there a non-kludgey way to do animation on 
the II? It would seem that it's going to be VERY hardware 
dependent. 


From: The Atom #397 
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Yes, the Mac II video card allows multiple screens, up to 8 can 
be page flipped via software control, if you are in 1 bit plane 
mode..(less if you are using more bit planes). 

It should give some really nice animation, and since most of 
the page flipping support is independent of the video card( other 
than using its ram), it shouldn't be as hardware dependant as you 
might think. 

Some people at Apple had one of the escher pics loaded into 
a Mac II with 8 different variations, when they ran the page 
flipping, it gave a really smooth animation of water flowing over 
waterfalls and canals, etc. 


Word 3.0... icch! 

From: Max 

Enough of the glowing remarks about Word 3.0! The release 
version is buggy (yeah, I bought it!), and shouldn’t be out on the 
market. 

Word 3.0 will spontaneously decide to inject triple-spaced 
paragraphs within a document. Word 3.0 also has a habit of 
inserting its own page breaks for no good reason (the only fix is 
to convert the file to MacWrite, and then to open it again with 
Word 3.0. Page breaks gone. No explanation.). 

Word 3.0 doesn’t work 100% with the Macintosh SE. Just try 
the command-shift-4 to select the next word. Nothing happens. 
Try it again, and the program crashes? Microsoft’s reply? “At 
this time, the keyboard commands you are using on the Macin- 
tosh SE don’t work, and there is no alternative.” 

Is this representative of a $395 word processor? I hope not. 
And this doesn’t even address the glaring omissions, like word 
count, automatic repagination, etc. 

Word 3.0 is a bad joke. Anyone who makes their living 
writing on a Macintosh has already figured this out. Does 
Microsoft care? We'll see! 


From: Gary Voth 

To all who have posted on the subject of Word 3.0, I think it 
is time to interject some balance into this discussion. 

First, mostof you whoarenew to this board will notknow me, 
but I have been a Mousehole regular since the dim days of 1984 
(early Cretaceous period...). Presently, in addition to being an 
IBM PC and Macintosh programmer, I have overall responsibil- 
ity for all technical, training, and product marketing literature 
produced by my company, a leading software development and 
consulting firm specializing in UNISYS Series 1100 mainframe 
systems. 

In the course of my work, I routinely write, edit, and design 
200- page technical product manuals. My view of word process- 
ing software is biased by the fact that I depend on it for a living. 
Icare about “insanely great" features only if they help me get my 
job done easier, faster, or better. I have personally used most of 
the top notch programs available, including WordPerfect, Micro- 
soft Word, MultiMate Advantage Professional, and WordStar 
2000 (haven't tried Manuscript yet). 

Microsoft Word 3.0 for the Macintosh is a word processor 
that satisfies both the “power typist” and the LaserWriter junkie: 
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get-down-to-business data entry and unsurpassed control over 
the printed document. Unfortunately, many of the things about 
Word that appeal to professional writers like myself have con- 
fused some Macintosh users who've grown up with MacWrite. 
(Unfortunately, The MacWrite Way will haunt every text editing 
program ever produced for the Macintosh.) 

Fact is, Microsoft Word works differently. Always has, 
always will. 

Most of the "problems" reported by casual Word users are 
simply things they don't understand about the program. Outlin- 
ing, for example, is not designed to be some nebulous “idea 
processing" feature. Instead, Word's outlining is a means of 
applying an underlying hierarchical organization to a document. 
Word can number section headings and generate table of contents 
and lists directly from the outline. You can "promote" and 
"demote" whole sections, and Words reflects this the next time 
you renumber or regenerate your tables. (The misunderstood 
"mark-text" option is provided only if you choose not to use the 
outline mode.) 

Similarly, the Plain Text attribute is designed to work in 
conjunction with Word's style sheets. Plain Textis not “normal,” 
but whatever is defined as the character attribute of the current 
paragraph style. Choosing Plain Text from the menu (or pressing 
Command-Shift-Spacebar) will override any manual text attrib- 
utes you have used and resets the selection to the underlying 
style. This is very handy if you use style sheets (and almost any 
serious Word user will). Ordinary attributes are easily ‘“de- 
selected" by toggling them. For example, it you select some bold 
text you will see that the Bold option in the Format menu is 
checked—choose it again to uncheck it and set the text to normal. 

Wordeven makesthe inadequate Macintosh keyboard useful, 
valiantly providing a keyboard shortcut for almost every possible 
command in the program. Borrowing from its own Windows 
interface, Microsoft even lets you select items from the menu and 
tab between dialog box options using the keyboard. (Tip of the 
week: select some text, press Command-Shift-E, and type 
"helv.") 

Word updates the screen in an incredibly complex fashion. It 
constantly draws off-screen bitmaps of adjacent screen pages in 
memory. 9046 of the time, this results in very quick scrolling and 
screen updating, especially for embedded object-oriented graph- 
ics (they are drawn once, then displayed as a bitmap). Once ina 
while you can get ahead of Word and cause it to hesitate while 
scrolling, or perhaps it won't completely update a section of the 
screen during some particularly complex event-handling se- 
quence—for my money, this tradeoff is minimal. Word is the 
first word processor on a graphics-based system that can scroll a 
page of text as fastas its counterparts on character-based systems. 

Of course, we could all go back to using LisaWrite... 


From: Jim Reekes #583 

Well, I understand how to use it. I beta tested it for MS and 
have the complete set of docs that I’ve read. 

The bug that always gets me pissed is the bizarre paragraph 
spacing that suddenly gets magically inserted all by itself. 
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For example, Print the document. Everything is cool and 
WYSIWYG. Save. Open the next day and print. WHAT THE 
HECKIS THAT!!?? In between paragraphs are BIG blank lines. 
Select the paragraphs and check the format. It still says ‘AUTO’. 
Looks fine on the screen, but will continue to print with extra 
spacing between paragraphs. 

The only way I've found to fix it up is to select the preceding, 
the in between, and the post paragraph and click on the [X] on the 
ruler to make them normal again. Then reformat them back to 
what you really wanted. Definite bug, fur sure. [Sounds like the 
Save command is dropping some information Word needs to re- 
construct the document. Whatever happened to simplicity in 
design yields dependability in practice? -Ed] 


From: Dr. Dog #295 

With all respect to Gary Voth (who is correct) there are some 
problems with Word 3.0 that are not just user misunderstandings. 
The other day, I found one involving repagination. Try inserting 
a hard page break (shift-enter) immediately followed (no visible 
or invisible characters) by a hard section break (command-enter). 
Then repaginate. The repagination algorithm loops endlessly, 
counting up dozens, then hundreds, then thousands of pages. 
Press command(-.) to break the cycle. I sent a letter to Microsoft 
telling them about this and just got a reply: *We are aware of the 
problem and are working on a solution..." The whole world 
waits for Word 3.05! 


Dr. Dog ( registered 3.00 user) 

From: David Valentine 

An infinite loop is a pain, but you don't lose data. Try a soft 
carriage return (shift return) with a box around it, with tabs for 
cols. it is ok when you enter the paragraph, but try and edit it. 
Sometimes works, others times its a real hassle. I haven't had 
time to go back and take a good look at what caused it, but it lost 
acouple pages of tables I was working on. My favorite is that the 
speller doesn't recognize the (option-n) n (n with atilde) as a 
character. I guess they don't use any foreign characters up in 
Washington. 


From: Tim Celeski 

Microsoft has been listening, it appears. Among other 
changes, they will be rushing out a new version in June. Free to 
registered owners. Bug fixes, and maybe a few new things. It will 
appear in the trades next week. [Microsoft says the Word 1.05 
update orders pending (some 2 or 3 thousand) are on hold 
pending the bug fix release. I called to find out about mine, and 
they said it takes four weeks just to get to your letter and open it, 
much less enter the order in the computer. -Ed] 


NEC Multisync 

From: Frank Henriquez 

I just hooked up an NEC Multisync monitor to a spare 512 
Mac motherboard, and it worked! The image filled the screen on 
the NEC, and it didn't lock to the vertical frequency right away, 
but a week of the vertical hold button produced a nice, steady 
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image of the insert disk icon and the cursor(in light pink and 
white...). I also read a letter in InfoWorld from one of the Nec 
folks who said that the Nec Multisync could easily scan up to 75 
hz...so this monitor **may** work with the Mac II. 


Disk Express/First Aid 

From: Power Hopeful 

I would be grateful for any help or suggestions for my 
following problem: 

I attempted to Disk Express my 40XP on a Mac SE. After 
twicereceiving the message that Disk Express could not commu- 
nicate with the hard disk, I decided to try it on a Mac plus, and it 
ran with no apparent problems. BUT later when I attempted to 
boot the SE with the hard disk, I began having many problems. 
I tried First Aid, which told me that the XP was not an HFS disk. 
I've tried many things, including re-installing the 2.2 driver 
(from Mac +) and replacing the system folder. At first on the SE 
it will seem to be functioning correctly, but after the Welcome to 
Mac msg, itreboots and won'trecognize the hard disk. However, 
it is working just fine on the Mac Plus. Also, on the SE I am 
frequently told that the XP is damaged and needs to be initialized 
(oh no!!). 

Can anyone help? How can I make the SE recognize the hard 
disk as an HFS volume? Or what else can I possibly try?? 


From: Jim Reekes 

Well Power, you've described many different problems. 
First one is running a DataFrame XP on the Mac SE. Supposedly 
SuperMac fixed this with init2.2. Maybe, maybe not. I don't use 
DataFrames. Secondly, after running DiskExpress you'll not be 
able to use Disk First Aid. Because you've wiped out a vol-info 
block used by DFA. The Finder maintains two copies of this 
block, the second block from the beginning and the second block 
from the end. DFA uses the second from the end. You need to 
use FEdit to read block#2, then write it as the 2nd from the end. 
Then try Disk First Aid again. 

Now, Гуе never had DFA do anything for me. So good luck. 
I would perform a complete backup (on the Мас+) and then 
format the drive. If you re-format the drive and it still gives you 
troubles, call SuperMac. 


From: The Anarchist 

Supermac Drivers before v2.51 were not completely compat- 
ible with ANYTHING except a Mac Plus or a 512e with a 
Supermac Dataport SCSI upgrade. Supermac has released INIT 
2.51, which is supposedly compatible with everything, including 
the Mac SE and Mac II. I know for a fact that the SE works fine 
with this version. 


From: Sam 
Іп response to what Jim Reekes said several posts ago about 
not being able to use Disk First Aid after having Disk Expressed 
a volume is only true for versions of Disk Express earlier than 1.5 
. The secondary VIB is correctly updated in 1.5 and up. 


. SystemTaskFrom: Bill Evans 
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We are advised by the Documentor In The Sky that it's a very 
good idea to call _SystemTask at least every 60th of a second. 
What are the consequences if we miss a beat quite often? Let me 
re-phrase that: If I ran an application for 24 hours which 
consistently called _SystemTask only every 30th of a second, 
what would be the side effects, other than lack of hair-trigger 
response to keyboard events, etc.? 


From: Chief Wizard 

SystemTask allows things like drivers to get control when 
they need it. Any driver that has the NeedsTime bit set in its 
header is checked during SystemTask. If the amount of time it 
specified has expired, the driver control routine is called. Sys- 
temTask is also used to blink the text edit insertion cursor. 

SystemTask does not affect things like the low memory tick 
count registers, or the movement of the mouse, or the posting of 
keyboard and mouse events. TickCount and mouse movement 
are handled during vertical retrace interrupts, and key presses 
cause their own interrupts (I think). 

So the net effect of not calling SystemTask often enough is 
pretty minute. DAs like the Alarm Clock may not update them- 
selves so rapidly, but if you’re running a 24 hr. task, you’re not 
likely to have desk accessories in use. 


PostEventFrom: The Atom #397 

Is there any easy way to set up the Event.where location of an 
event that I post with PostEvent? I'd like to process certain 
keydown events to act as if the mouse was actually pressed in a 
control button. 


PostEventFrom: Lsr 

On 128K ROMs you can use PPostEvent, which returns you 
a pointer to the event queue entry. Then you can modify the 
queue entry. For all machines, you can create an event queue 
entry and call the Enqueue function to put iton the event queue. 
Look at the OS Event Manager & OS Utilities chapters of Inside 
Mac. 


Trap patchingFrom: Don 

I've been working on a patch for GetResource and I' ve been 
running into some problems. First, a little background ... My 
patch is an 'epilog' type, that is, it must be called after GetRe- 
source has done its thing. Even though GetResource is already 
patched at system startup with an intercept that nastily looks at 
return addresses, my patch still works as an epilog. For those of 
you who might be unfamiliar with these terms for our problems, 
consult Scott Knaster's ‘How to Write Macintosh Software’ 
appendix B. Anyway, everthing's hunky догу except when I run 
ResEdit or Font/DAMover. ResEdit is particularly nasty — 
because the Mac resets when you try to open a resource, I think 
the darn thing is generating a bus error. Other times it just begins 
writing wildly to video and sound memory. Font/DA Mover does 
the same thing. What's the problem? I know what you're think- 
ing. They're patching GetResource too! Wrong. To the best of 
my abilities to check this, neither program re-patches GetRe- 
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source. So I'm stuck. If you have any ideas, any wild 
speculations, anything ... leave me some mail here. 


MacMemory TurboMax upgrade 

From: Max 

Well... the results are in. I have just completed my review of 
the MacMemory TurboMax upgrade for the Macintosh (in fact, 
the Official Review will appear as an article in the June issue of 
MicroTimes - a freebie, available at enlightened computer deal- 
ers throughout California) 

It's fast. It's fun. It is compatible with ALL Macintosh 
business software, and also compatible with all the DA’s I could 
throw at it, as well as most games (surprise!). Speed? Throwing 
a TurboMax into your Mac will cut 20% to 40% off the process- 
ing (“wristwatch”) time for most applications. I tested one with 
the optional 68881 co-processor. I'm sure that helped when it 
came to absolute number-crunching speed. 

Value? That's a gray area. The TurboMax is based on the 
68000 CPU, rather than the 68020 of Levco's Prodigy 4, or the 
(soon-to-be-released Mac II). For performance, the Prodigy 
ABSOLUTELY KILLED the TurboMax. Atthe same time, the 
Prodigy isn't quite compatible with all existing software: some 
bizarre programs like Pro3D won't run on the 68020. 

In the final analysis, if you're stuck on Macintosh software 
that's available RIGHT NOW, the TurboMax is the cost-effec- 
tive hot-rod upgrade for the Macintosh. If you're concerned 
about future compatibility with applications written for the Mac 
II, the TurboMax is a stop-gap measure: one which exploits the 
existing technology, and will probably be obsolete by the end of 
this year. 


68020 

From: Power Hopeful 

As you may know, I was at one time using a 68020 in my Mac 
Plus. I had SO many problems (mainly address errors) that I 
removed it. In all my studying — both casual and serious — I 
never came across one item that referred to this problem, and I 
just assumed the problem was with the particular board I was 
using, not with the 68020 generally...Lo and behold that today I 
see a line in MacWorld flatly stating that a large percentage (was 
it 50% or more?) of current Mac software is incompatible with 
the 68020! I don't think this is a generally known fact, and 
certainly the mouth watering ads and hype about the fabulous- 
ness of the '20 neglect to mention it...But my mouth still waters... 
and inquiring into Levco's Prodigy SE: it's selectable, i.e., a 
keystroke(or two?) can switch you back to your 68000. This 
feature should be seen as absolutely necessary, as you have an 
almost useless — and certainly unpredictable — machine with- 
Out it. 


From: Cpettus 

I'm not sure I credit the statement that 5046 of the existing 
Mac programs will be 020 incompatible. If a 68020 equipped 
system is getting BusErrors, then the problem is DEFINITELY 
in hardware; Address Errors might be software, but the 020 is 
more permissive than the 68k on strange addressing (loading a 
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long from a byte boundary, etc.). 

In general, the things that make a program 020-incompatible 
are self-modifying code (running afoul of the 020's cache) or 
playing games with the interrupt stack frames (which are differ- 
entamong almost all members of the 680xx family). I doubt that 
50% of all Mac programs are THAT misbehaved, and reports 
from Prodigy 4 owners seem to bear this out. 

On the other hand, I suspect that incompatibility with | exist- 
ing (note the emphasis) applications will get worse, not better, 
as the Apple system software evolves. The Mac lets programs get 
away with a lot right now that will probably be forbidden in the 
not-to-distant future. For example, right now a program can write 
to the screen directly; this will probably be “unsupported.” [Or 
impossible, since the video is not part of the Mac II motherboard 
RAM; programmers must agree to use the standards Apple 
establishes if the hardware is to grow in power without restric- 
tion. That is the beauty of Quickdraw. It eliminates the confusion 
of the CGA, EGA, VGA nonsense. -Ed] 


From: Power Hopeful 

I always appreciate words from those who REALLY know 
about this stuff. I was interested in the fact that those with Levco 
boards seem to be having fewer problems than reported. Actu- 
ally, one of the reasons that I wanted to mess with the 68020 was 
to try some status separated (supervisor v. user) ideas I was 
interested in. The ‘020 has a number of additional instructions 
along this line, as well as enhanced stack-saved information on 
errors. I tried for a long time to generate bus errors with little 
success. My point is that all my software problems were address 
errors, and speaking of such, I’m experiencing some on my SE, 
most notably (besides “геѕіагг”) with Nosy and with SuperMac's 
print spooler. The latter breaks my heart, as I am chained to the 
noisy Imagewriter with no draft mode from MPW! 

Our discussion of the 68020 and possible incompatibilities 
clarifies the question that I’ve had all along about the situation. 
I’ve read and heard that the 68020 is downward compatible with 
all members of its family, but obviously its different abilities 
must be reflected somewhere. Does the hardware involved cause 
the problems? I mean —if this is not an Apple secret — are the 
data/address bus expectations of a 68020 living in a current Mac 
different from what is actually there? Maybe you can see that I 
have only a rough understanding of hardware, but I’m really 
interested! 


From: Cpettus 

Interms of its physical package (i.e., what all the little pins on 
the outside of the chip do), the 020 is completely different from 
the 68k; not even close. This isn't a source of software incom- 
patibility, per se; the program still "sees" the same kind of 
addressing space, only bigger, than it saw before. 

The 020 is downwards compatible, TO AN EXTENT, with 
the other members of the family. There are, however, some 
differences, and those can be killers. The stack frame on an 
interrupt is one, the presence of a cache (which makes self- 
modifying code even less of a good idea than before, if such a 
thing is possible), and such are related. 
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Then, there is the issue of addressing space. On the 68k, one 
only had 24 bits of addressing. The address registers, thus, only 
could store 24 bits of data; try as you might, A0-A7 would always 
report back 0 in their most significant byte. Apple took advan- 
tage of this in several places in the MAC OS (the Resource 
Manager being the worst offender) to keep an extra byte of data 
around associated with each 24 bit address (ie handles). 

Enter the Mac II, and thus enter more than 16 meg (possibly) 
of user RAM. Those bits that they were using for other things 
(such as the resource flags) are now needed if the user is to have 
more than 16 megs of memory managed by the Mac Memory 
Manager plugged into the system. This is, after a fashion, the Mac 
equivalent of the IBM PC 640k limit; fortunately, I think the Mac 
limit will be more easily lifted. 

I think most programs written in high-level languages using 
reasonable development tools will be compatible. Some pro- 
grams which take considerable liberties with the Mac system will 
fail. Apple's Tech Note #117 is 28 pages of compatibility 
guidelines, and covers the subject pretty well. 


MPW And Font Manager 

From: Ram Warrior 

Has anyone noticed a problem with MPW Pascal and the Font 
Manager? 

Wheniniting the Font Manager, several constants are defined 
for special characters i.e. checkmark, blank, etc... In the past I 
have used these constants for inserting and removing special 
characters next to menu items. I am now using MPW and for 
some reason they no longer seem to work. Everything compiles 
just fine, but no checkmarks or other special characters. 

Any thoughts? ideas? suggestions? 

I am now using CheckItem instead of SetItemMark and it 
Works fine for checking an item, but I still have need to put other 
characters next to a menuitem. 


Menu Icon Bug 

From: Rick Boarman 

My last conversation with Cupertino about that got nowhere. 
They said not only is it a bug but it has become a feature. They 
tried to code some routines to fix it but nothing worked! I can’t 
believe Apple’s programmers can’t figure out such a seemingly 
simple bug. 


Window Question: 

From: Ram Warrior 

In an application I’m writing in MPW Pascal, I use a window 
defined as follows: 


resource ‘WIND’ (1000, window") { 
(44, 7, 335, 505}, 
noGrowDocProc, visible, GoAway, 0х0, “window”... 


To the best of my current understanding this should yield a 
window with only a go away box, and the title “Window”. 
When the program starts, the window is fine, but when a menu 
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item is selected, and something is put in the window, the bottom 
and right edges, appear to have the outlines of scroll bars controls, 
and the bottom right corner has а “size” box in it. Is this a problem 
with the window control list? 


noGrowDocProc 

From: Chief Wizard 

When you specify a window definition procedure of noGrow- 
DocProc, you’re telling the window manager which WDEF to 
use to handle the window. This WDEF is called upon to draw the 
window, calculate its regions, and to hit-test the mouse. That is, 
the WDEF determines what to return when you call FindWin- 
dow. By using the WDEF for these things, you can writea WDEF 
that creates an unusual custom window that may have things like 
the grow box and the go-away box in non-standard locations. 

If you specify the noGrowDocProc WDEF in your Rez source 
file, the WDEF that gets used will NEVER return inGrow when 
you call FindWindow. After all, you specified no grow box. 

HOWEVER, the WDEF is NOT what draws the grow icon 
(and the lines for the scroll bars). When you want the window 
updated, you must draw these items yourself in your update 
window routine. To do this, you call the routine DrawGrowlIcon. 
If you don't call this, no grow box will be drawn. 

I suspect that what's happening is that when you put some- 
thing in your window you get an update event. Then your update 
routine mistakenly calls DrawGrowlcon. Simply remove this 
line. Did you, perhaps, take some of your code from an example 
or other program that does have a growable window? 


Window Manager Port 

From: The Cloud 

What is the “official” status of the Window Manager Port? 
i.e. can I draw in it, or is this frowned on? I'd like to be able to 
implement a ZoomRect procedure to draw the zooming rec- 
tangles that one sees when double-clicking something to “open” 
it... Also, when I set the current port to that returned by the 
GetWMgrPort call, I find that nothing happens if I have previ- 
ously made a window invisible (by calling HideWindow0O ). If I 
simply CloseWindow, the drawing routines work fine, but then 
I have to get the window all over again. Any insights would be 
appreciated! 


wMgrPortFrom: Micro Ghoul 

The official status of the wMgrPort... The application did not 
create it, so don't play with itor the layer manager will eventually 
wake-up and byte your nose. 


Transfer using Launch w/Lightspeed C 

From: Mark Chally 

I'm writing in Lightspeed C 2.01 and know *NOTHING* 
aboutassembly. How wouldI go about writing a Transfer routine 
(that does a SFGetFile, of course) using inline assembly? I 
imagine it would look something like: 


Transfer() 
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SFReply reply; 


SFGetFile(getPlace, NIL, NIL, 1, “APPL”, NIL, &reply); 
if ('reply.good) 

return(FALSE); 

SetCursor(& waitCursor); 

asm ( 

move.l reply.fName, (А0) 

move.] OL, 4(А0) 

_Launch } 


but I'm sure the assembly stuff is way off. Any hints would 
be greatly appreciated. 


From: Larry Nedry 
Why do it in assembly ? 


Transfer () 
( 

Point 
SFReply 
OSErr 


digOrigin; 
theReply; 
Error; 


SetPtC&dlgOr igin, 82,71); 

SFGetFileCdlgOrigin, OL, OL, 1, “APPL”, OL, &theReply); 
if CtheRep ly. good) 

( 


Error = SetVo1COL, theReply. vRef Num); 
Launch(@, & theRep ly. f Name); 

) 

) 


This routine will return if cancel is selected. Larry 


Files and ram cache 

From: The Corsair 

Ok, for my file save routine, I сай Create(), ЕЅОреп(), 
FSWrite(), and FSClose(). If Ihave the control panel RAM cache 
on when I do a save, it doesn't even turn on the disk and I am 
assuming doesn't update the disk until I do a quit. (this can be a 
real bummer) Is there some extra call that I need to do to override 
this? 


From: Rick Boarman 

Yes, FlushVol will flush out the cache buffers and the file 
manager buffers. I call it after I do any serious file IO (like a 
save). 


Benchmarks: Isoemac 

Does anyone know where I can get the code for the following 
popular benchmarks: Whetstone, Drystone, Orbit, Sieve, and 
FPBenchmark? 


From: Jim Reekes 
I called Motorola and asked for a copy of MC68020 vs. 
80386. Besides being a real cool thing to have by allowing you 
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to argue with IBM heads, it also lists the popular benchmark 
source code in standard format. (not like the version that was run 
by Intel when reporting result on the ‘386) The listing are in 
Fortran, Algo, and C. 

Motorola: 1 800 521-6274. Ask for a copy of the Apples-to- 
Apples comparisons. 


From: Frank Henriquez #141 

Motorola is **ТОО** conservative on their benchmarks; in 
their 68000 vs. 80286 comparison, they were pretty lenient with 
the 80286, and it still came out looking like doggy poo when 
compared to the 68000. In the 68000 vs. 80286 manual, they also 
provided source code - including a great little assembly language 
Quicksort routine that I adapted for other uses with only minor 
mods. 


From: Cpettus #484 

Actually, Motorola has always played very straight with their 
benchmarks, a refreshing change in an industry where bench- 
marks are about as reliable as ramp-up dates on production. It 
was nice to see M finally go after Intel’s completely bogus 
benchmarking suite: the 020 is, in many circumstances and MHz 
for MHz, a better processor than the 386; in a cost limited 
environment (i.e., you can't buy fancy external caches for the 
386), there IS no comparison... 


TML, MDS, & MacApp 

From: Worker 

Well, shortly after my last message on this subject (3 days), 
I hit a wall that I didn't feel like climbing. TML's lack of 
PROCEDURE and FUNCTION parameters makes it next to 
impossible to convert MacApp to compile using the 2.0 com- 
piler. So, I gave up and went back to Smalltalk-80. Right now, I 
can get more real work done with it, and it's undoubtedly the best 
introduction to object-oriented programming that money can 
buy. Daryl Lovato at TML said they will begin working on 
MacApp support once they finish the Pascal compiler for the 
IGS Workshop. Late summer, at least, I'd guess... 


EPSF FilesFrom: 

Rob Humble 

Does anyone have any experience with EPSF (Encapsulated 
PostScript File) type files? I downloaded ArtBrowser form 
MHDL and like using it with the demo files provided, but what 
other use is it? I have generated EPSF files with Cricket Draw, 
but ArtBrowser won't recognize them. And PageMaker 1.2 
won'trecognizeany of them, demos or C Draw made. What's the 
deal with EPSF files anyway??? 


ArtBrowser: Dave Kosiur 

Itook another look at ArtBrowser since I originally got it. It's 
not ArtBrowser's fault that it doesn't recognize Cricket Draw 
EPSF files - it’s the fault of Draw! I saved a simple Draw file as 
spheres.epsf after clicking on Draw's EPSF option in the Save 
As... box. After exiting CDraw, I found 2 files called 
spheres.epsf! One was in the proper folder, the other was one 
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level higher. The one in the right location had no resource fork, 
therefore it had no PICT resource for ArtBrowser to display. The 
other file had А resource fork, but something else was missing - 
ArtBrowser didn't recognize it (come to think of it, I think it was 
a text file). Using ResEdit, I pasted the PICT resource from file 
B into file A and, lo and behold, ArtBrowser recognized it and 
displayed it properly. 

It looks like Cricket Draw has a programming bug when it 
comes to creating EPSF files. I’m planning on phoning them 
tomorrow to let them know. 


More on EPSFFrom: Dave Kosiur 

I called Cricket Software today - they were aware of the 
problem with the encapsulated files created by Cricket Draw 
(internally, that is - I was the first user to bring it their attention). 
Someone in Tech Support said that they are currently testing a 
new alpha-release and the EPSF file bug is one item that’s 
addressed in the new version. Just thought you'd like to know. 


APDA Response: Dave Cochran 

Im concerned with the reports in MacTutor on APDA's 
customer response. In the last two months, APDA has been fill- 
ing orders quickly and responsively. If you have any doubts 
about ordering from APDA, feel free to call them about it. 


Vol. 3 No.7 


1st MAC Clone 

From: Julio Carneiro 

As the MAC II is starting to be shipped, a MAC Clone is 
hitting the stores here. This is a 512K MAC (64K ROM's!!!). 
Can You guess the price for it (4-5K). Can you imagine that??? 
The only difference is that it uses a 800K internal drive (running 
MFS). Anyone interested in developping software to this ma- 
chine (called МАС512) "eh! eh! eh!". They have changed the 
Apple menu to a butterfly menu (ugly), I think to get rid of been 
sued (eh eh eh).... Their plans isto build (and sell) 300 МАС512/ 
month??? THIS IS NOT A JOKE. I HAVE SEEN THE MA- 
CHINE. IT IS REAL. 

MacApp Paint 

From: Lsr 

Well, MacApp Paint was mentioned in the November (or 
maybe December) 1986 issue of MacWorld. If any one has gone 
toa MacApp talk (at Mac World Expo, for example), the program 
is generally shown as a demo of MacApp. My purpose in writing 
it was to demonstrate that writing a program using MacApp and 
object-oriented programming doesn't mean you have to sacrifice 
performance. For a window that's about the MacPaint size, the 
performance is very close to that of MacPaint. If you make the 
window larger or draw large shapes then the performance 
degrades proportionally. 

The program implements the easiest features of MacPaint/ 
FullPaint. You can draw rectangles, ovals, lines; the paint brush, 
eraser, and spray paint works, the marquee works (moving, copy, 
paste). The more recent versions have text and scaling (1-16 
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times). Since the program is written using MacApp, it has 
autoscrolling for all operations. Unlike FullPaint, you can draw 
a rectangle (or anything) the size of the document. Also, the 
window can be expanded upto the size of the document. You can 
also open as many windows are you have memory for. (To be 
fair to FullPaint, their design center was a program thatcould edit 
4 docs at once on a 512K machine; they also implement some 
complicated commands that require multiple offscreen buffers, 
each of which has to be as large as the largest area you can edit 
at once. To satisfy all these constraints, they limited the maxi- 
mum edit area to the size of the std Mac screen.) 

There is alsoa version of the program that does color on a Mac 
II. (Same sources, with conditional compilation.) This version 
works with 8-bit deep color images; the speed is about the same 
as the balck апа white version on a Mac Plus. As Jim implied, 
MacApp Paint is a demo and it is not being distributed. The 
MacApp product manager is tryingto get permission to distrib- 
uted the application through the MacApp Developers Associa- 
tion. The main problem is that the application has enough 
features that developers might complain that Apple is doing 
application software. Also, users might think that this was a pre- 
release of a new Apple product. (In reality, there are no plans to 
make this into a product.) 

If people are interested, I am willing to discuss some of the 
implementeatio details. In particular, the way in which the 
objects are structures is fairly interesting. (For example, there is 
a Bitmap object that manages the offscreen bitmaps.) I don't 
know if this should be the exact place, or if the discussion should 
move to the MacApp section. 

MacApp Paint palettes 

From: Lsr 

Jim also mentioned the MacApp Paint palettes on the Mac II 
(and other large screens). On the std Mac screen the palettes are 
in the same place as with MacPaint. If one were to position the 
palettes at the same place on a large screen, they would fall in the 
middle of the screen. To counter this, I explicitly move the 
palettes down so they are out of the way. I also make the default 
window size bigger, to take advantage of the extra screen space. 
I think this arrangement works out best. Accessing the palettes 
is not too bad, because the palettes are also available in custom 
menus. You can zoom a drawing window to the full screen size 
(covering the palettes) and still have full access to everything 
through the menus. On later versions of the program, I 
implemented a hack in which Cmd-click in a palette allows you 
to move it. My palettes are implemented as real windows, which 
never come to the front. So you can click on a tool in the palette 
and immediately begin using it without having to change win- 
dows too much. 


New System 4.1 

From: Jim Reekes 

System 4.1 is a major revision. I may have been pessimistic 
about 4.0, but nowIfeel more confident with the new release. 3.2 
gave us meat, and 4.1 is the potatoes and gravy. I do have a 
question regarding Apple's documentation of the changes. RE: 
‘DRVR’ (18,.Control Panel, Purgeable) [4612] The RAM cache 
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arrows and size indicators do not appear if the control panel is 
running under switcher or twitcher. QUESTION: What's a 
“twitcher”? [A new version of Switcher they've been juggling 
with?- Rusty] 


PRINTING 

From: Power Hopeful 

I have tried printing in draft from MPW w/ the the mentioned 
configuartion to no avail. I noticed that of the 3 ‘PREC’ 
resources, two were identical save a 1 and a 0 at the offset where 
I figured the spool vs. draft offset to be. I assumed MPW was 
always accessing the one w/ spool, so I changed the id's around. 
TO NO AVAIL again. I've noticed also that any app that offers 
a job dialog box prints only in Monaco when draft is selected. 
This, as I’ve mentioned many times, is a major source of irritation 
to me, and I'd appreciate ANY suggestions to be able to print 
accurately in draft mode. By the way, does anyone want me to 
beta-test their Mac II?? 


Does it run? 

From: Frank Henriquez 

Tried several programs on the Mac II today. The first was 
Turbo Pascal. It loaded fine (and even opened up the window to 
the edges of the Mac II screen - nice touch). I compiled the 
standard MyDemo.pas (which compiled in 1 - 3 seconds) and 
then ran Mydemo. That also worked. (The Sieve gave a time of 
1.1 seconds, vs. a standard 512K Mac time of 5.9 secs). The only 
problem (albeita MAJOR one) was when I tried to quit the demo 
and return to Turbo. It crashed the machine. After some thought, 
I figured it had to do with lauching one program from within 
another. 

Then, we tried LightSpeed Pascal, and it died a miserable 
death - Ше editor did strange things to the menu bar, and in 
general Lightspeed acted in a very unfriendly way. The last 
program I tested, for sentimental reasons (it being the first 
program I bought for my Mac) was MacASM. As expected, it did 
not work, writing garbage to the screen. It DID however, accept 
by typed command to quit to the Finder. Frank 


Where's the color pallet? 

From: Jim Reekes 

Hey man, I had used a pre-release Finder on the Mac II that 
allowed me to choose my own colors. There was a ‘Color’ menu 
next to the 'Special' menu. Then by selecting an icon or folder, 
I could then go to the menu and select a color for it. This way I 
had all my folder in green, utilities in blue, applications in red, 
and documents in yellow (or what ever). I could even ‘View by 
Color’, which was just like view by name but the folder/files were 
sorted into groups according to their colors. Neat! And where's 
the Color Pallet? There is suppose to be a ‘cdev’ in the System 
Folder so that when I open the control panel I could rearrange the 
color spectrum. As it is now, all the colors at one end of the scale 
appear in a olive green (yuck). 


TMON patch 
From: Jim Reekes 
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TMON crashes with the new system's control panel UN- 
LESS you make the folowing patch (on a backup copy of course) 
Find “4278 00BA 4278 00BC” in the control panels General file. 
Replace with “4268 ООВА 4268 O0BC". Thank you Larry. 


Mac Il report 

From: Jim Reekes 

Well, there is a problem with the PRAM on the Mac II and 
SCSI drives. Certain system crashes will cause the Mac II to 
ingnore any SCSI devices currently attached. I have three hard 
disks on-line. All of them are valid, bootable volumes. But 
sometimes I’ve had the system bomb and then had to reset. After 
that I only get the flashing ? icon. (Interestly enough, the drives’ 
access lights are flashing too. So, appearantly the Mac II realizes 
there are SCSI devices attached but refuses to mount them.) I 
can boot from a floppy, but it will still not mount the hard disks. 
If I use the 'SCSI Bus 2' cdev, they can be manually mounted. 
This is strange. (I think this is a problem with the Startup 
Manager.) The only fix is to zero out PRAM with the Shift- 
Option-Cmnd routine while opening the control panel. Only one 
time did this not work. I don't think it really zero'd out the 
PRAM, this may have beena problem with the new control panel. 

This problem has happened to me at least once a day. This 
morning it happened while printing 20 copies of a Word 3.0 doc. 
About the 14th copy came out, then “SYSTEM BOMB ID = O1". 
Reset, but no booty. Zapped PRAM and it works. This also 
happens when trying to use *MacZap Hard Disk Recover". 

Another bug report: Don't use DiskExpress on a Mac II yet. 
Ilove this util and have always recommended it. But on a Mac 
II and certain drives it has problems that may corrupt the disk. 
Stay tuned for further info. 


Consulair & 4.1 

From: Richard Scorer 

Ihave seen this kind of warning before, but I believe it's. not 
Consulair but MegaMax which has this problem. We have 
Consulair in-house, and have no problemsatall. The otherreport 
which said it was Megamax said they had hard coded the globals 
(I think - I don't have my message dump handy). 


Patching Apps Under 4.1 

From: Lsr 

The patch mentioned above tries to redirect applications that 
used location $02B6 (which was reserved by Apple and is now 
used in System 4.1) to use location $0A78 instead. The later 
location is the start ofa 12 byte application scratch area, which 
is reserved entirelt for applications. If you want to apply this 
patch, there are 2 things to keep in mind. (1) Notall occurrences 
of $02B6 are referring to the low memory global; ideally you 
would want to make sure that this was part of an instruction that 
actually refers to the memory location. (2) The application might 
be using the scratch area already. (Since there are 12 bytes in the 
scratch area, you might be able to patch it to use some other part 
of the area, however.) 

Information Technology: Health Sciences 

From: Dr. Dog 
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I just returned from Memphis, where I spoke at the Apple- 
sponsored conference “Information Tech...etc.” There were 
some interesting medical things going on there, including 
several previews of several medical data- base managers (Mini- 
medline), artificial intelligence programs for medical decision 
making (including ours, Iliad), and several interesting third party 
displays. One of the best third party programs was demonstrated 
by Bill Appleton. 

“Course Builder” is a program that builds stand-alone teach- 
ing applications using an iconic, modular set of programming 
blocks. One can build multiple choice questions, branch 
randomly or deliberately from one set of questions to another, 
integrate graphics, etc. Billintegratesa paint program, a draw 
program, animation, and digitized or Mac In Talk sound support 
into his product! А planned update, to be called video builder, 
will integrate videodisk and/or 8mm video tape into the product. 
Imagine building a medical pathology lesson (or sales training 
product, etc) that can display various video images at certain 
times. Incredible... He gave me a demo disk that will not save 
and said I could upload it to the M/H down loads, which I will 
try to do soon. On the lighter side, he is working on a new game, 
called Apache Attack, involving helicopters flying through a 
cityscape. It was not yet done, but the demo looked impressive 
(unfortuna- tely, no demo disk here). 

Overall, it was a nice conference, with several hundred 
participants. Apple treated us well, with nice food, a barbeque 
with blues band at a local college, and good accommodations. 
Only two Mac 1° were present: one from Apple and one from 
athird party developer. The Apple sales manager for the western 
region told me that only a few of his sales offices even have Mac 
II yet. Brigham Young University (south of us here in Salt Lake) 
got 20 MacIIs into the bookstore, but they are only available to 
departments, not to individuals. Furthermore, they all have 
monochrome screens, no HD, and the regular keyboard. I was 
told they can't sell them—everyone wants color, extended 
keyboard, HD 40, etc. We were told that we'd get developer 
machines in mid-late summer. 


New System Probs 

From: Jack Connick 

Well, I’ve been running the new system 4.1 etc. for about a 
week now. Ran into a few problems. Excel will crash if you go 
to close any opened DA, pretty consistently. I’ve also noticed 
that upon a cold start up in the morning, the mouse control has 
switched itself to its slowest position, “tablet”. This has occured 
onmy SEandonaPlu Anybody else? Jack 

Word DCA Convert bug 

From: Jack Connick 

Latest in my litteny about Word 3.0 bugs, is that their DCA 
convert utility doesn’t work. I had occassion to get a file 
transfered from aclient’s IBM mainframe, and when she said she 
could save it into DCA formatt, I thought “Great that'll convert 
using that utility that came with Word and save me lots of editing 
time." 

Wrong. After having it XModemed down it wouldn't con- 
vert. The error message said something like "There's no DCA 


© The Essential MacTutor, Vol. 3 


compatable text file present" What a bummer...called MS, they 
thought it was in the transfer. I thought that was BS because if 
a file transfers XModem it's error free. Called my good friend 
at Aldus, who knows more about MS Word files than MS, he said 
“Just rename it xxxxxxxx.DCA (X=name, no more than 8 chars) 
and try placing it directly into PageMaker 2.0." Well, lo & behold 
it worked! Same file as before, that wouldn’t work with MS 
word’s utility. 

So there’s the work-around. I exported the file back to MS 
Word 3.0 formatt and did some cleaning up, but nothing like 
working with an ASCII file would of been. Try PageMaker’s 
Export feature if your’re having problems with Word 3.0 files. 
It writes better files than MS Word does. 

System 4.1 

From: Gary Voth 

Well... System 4.1 seems to be a real watershed product. Iam 
truly amazed at how many things have problems with it. 
Although I think Apple will take a lot of misdirected heat in the 
trade press for releasing “unstable” software, the obvious 
conclusion is that 4.1 heralds the beginning of a new ballgame 
with new rules to follow. I suspect we had all better cinch up our 
belts and get used to it. 

One word of advice. With previous System releases it was 
usually safe to bypass the Installer: you could simply drag the 
new System off of the release diskette and off you go. NOT 
ANYMORE. Now there are at least four baseline machine/ROM 
architectures in wide (or soon to be wide) use. The System really 
must be tailored for your computer. (I know the SE looks like 
a MacPlus and has only slightly enhanced performance, but keep 
in mind that it is totally reengineered from the ground up.) 

I tried running for awhile with some extraneous Mac SE/Mac 
II resources in my System file (I have a 512E with a Levco 
MonsterMac) and found all kinds of problems. Macsbug would 
hang, MacTerminal (which loads new keyboard templates) 
turned the keys into trash, etc., etc. I finally realized what was 
happening and launched the Installer using the Mac 512, 512E, 
Plus installation script. Things have been MUCH cleaner ever 
since. If you are experiencing problems and you haven't run the 
Installer, give it a try. 


Poor Old Switcher... 

From: Gary Voth 

Gee, poor old Switcher, once everybody’s darling, sure seems 
to be getting alotof bad-mouthing lately. Frankly, I use Switcher 
almost daily ina 2MB environment and have found it to be pretty 
reliable. Insiders will tell you that most of the problems encoun- 
tered when using Switcher relate to poor memory management 
by the client applications. To maximize memory use, most 
people run applications under Switcher in relatively small 
partitions—usually odd sized ones at that. Programs which 
operate flawlessly in 512K can be walking (er, running) time 
bombs when operating in 320K. With older programs which do 
not handle Switcher events, Switcher uses a rather clever 
technique to implement Clipboard conversion. This involves the 
use of a “fake” desk accessory. The application is made to think 
that the user has activated a desk accessory, which triggers (in 
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most programs) an update of the system desk scrapsothatthe DA 
can access the data that has most recently been cut or copied. 
This particular sequence of events can eat up a lot of heap space, 
easily compromising an application running in a tight “world.” 

On top of that, many users have never learned how to use the 
Option key to transfer the Clipboard between client applications, 
so they mistakenly keep the “Always Convert Clipboard" option 
checked. This is just asking for trouble, of course. 

Toconvince yourself that Switcher is probably not the culprit 
the next time the system error alert appears, try using the 
"emergency exit" —Command/Option/Shift-Period)— to es- 
cape from a hung application. Nine times out of ten it will work, 
at least allowing you to exit any other installed applications 
gracefully. 


Mac 2 compatability 

From: Jack Kobzeff 

Well, we've been running our Mac 2 for about 2 weeks now. 
Thelist of totally incompatable software is suprisingly short. 
The programs that won't work (that we've found) are..... Mac 
Write Mac Zap Recover Mac Basic 1.02 MicroSoft Works and 
afew PD items.... But that's about it! Even Mac Paint 1.5 works 
likeacharm! (in it’s regular sized window) Mac Draw 1.9 works! 
I’m kinda impressed that so much WORKS. Now if we could get 
some software that could really show off the new features of the 
2. Oh, BTW, we hooked up our AST 2000 to the 2, and it works 
like a charm. Didn't have to reformat, or change a thing. 


Prodigy SE 

From: Max 

Just installed a Levco Prodigy SE in my Mac SE. Current 
configuration is 16-mhz 68020, 68881, and 2-meg RAM. As 
would be expected, Ше speed increase is genuinely awesome... 
beyond belief... stupendous... etc. What's nifty about Levco's 
arrangement is you can "Jobotomize" (disconnect) the Prodigy 
board by hitting the Interrupt switch during Shutdown. А neat 
trick: for some of the writing I do, I have to use (icch) Tempo, 
and Tempodies ahorrible death on the 68020. Simple: Interrupt, 
reset, and you've got a garden-variety 68000, 8-mhz Mac SE. 
Do your dirty Tempo business, save the file, Interrupt, Reset, and 
you're back up to a Prodigy! For System 4.0/Finder 5.4, the 
controls for the Prodigy reside ina “module” for the new control 
panel. Select the module, and you can turn on/off the 68020 or 
the 68881. In short, you can configure an SE to run like a Mac 
II, a standard Mac SE, or anything in between. AND... Levco 
has just lowered the price for the basic Prodigy SEto $1499. For 
68881, add $300. For 2-meg, add $500. I think this means that 
MacMemory's TurboMax board is dead. 


Shutdown worries 

From: Jim Reekes 

This new ‘Shutdown Manager’ has me worried. I've always 
been concerned about the Finder updating my VCB (volume 
control block) with bogus data. How many times have we 
perform the Finder's shutdown and later returned to the desktop 
reading the message “disk is unreadable, cancel or initialize”? 
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Page 237 of S. Knaster’s book ‘How to Write Mac Software’ 
reads... “WARNING: After an application has crashed, the 
System is in an uncertain state. System globals of system heap 
objects may be damaged. If you use the debugger to exit to the 
Finder, everything may appear to be in good shape, but beware. 
The safest thing to do is to reboot after a system error. If you save 
your disk just once, you won’t regret the small inconvenience of 
rebooting.” Now consider this new ‘feature’ of System 4.1, the 
Shutdown Manager. I'm running an application and get the 
bomb dialog. Now, toclick or notto click? Thatis the question. 
I'm worried when I see the ‘System bomb’ dialog because, if I 
click on Ok, then the Shutdown Manager is going to flush my 
volume's buffer back to the disk, which maybe garbaged data. 
My disk would have been in perfect condition, until that bogus 
VCB was written to it after clicking Ok. I’m especially worried 
because so far I’ve not seen a program thatcan replace abad VCB 
with the proper info. Only one util that I know of can get around 
this bogus VCB, MacZap. This means I may spend the rest of 
my day trying to recover my hard disk because I clicked Ok at 
the system bomb dialog. I hope I'm wrong, but I am worried 
about this. 


Macsbug 

From: Power Hopeful 

I'm having trouble with the new Macsbug. There seems to be 
a different/no "DM" command. Am also having trouble with 
"Rxx" and "WH" commands. 


From: Larry Nedry 
Use lower case in the new Macsbug. 


Undocumented Features 

From: The Wombat 

Ап expanded launch trap that supports sublaunching is de- 
scribed in apple tech note 126. Sublaunching means that when 
a sublaunched program is terminated the calling program is 
launched instead of the Finder. This is a means by which an 
MPW like shell can be implemented. Whate Apple doen'ttell us 
is that a sublaunch can be over-ridden by holding the the option 
key, a normal launch is performed instead. 


Declaring data 

From: Power Hopeful 

I very much enjoyed David Smith's articles in the current 
MacTutor. I was wondering if someone could clarify a few 
points concerning data declarations and Mac II compatibility. 
He mentions that the practice of DC's and then changing their 
contents won't work, as won't DS'ing within your program 
space — that all data should be declared relative to AS. He notes 
also the separation of code and data spaces, which I interpret to 
mean something to a more stringent degree than that of the 
current situation (i.e., before Mac II). 

First of all, why can one not declare data in his own program 
space? Does this have to do with the 68020, memory manage- 
ment, multitasking or some combination of them? The only 
reason that comes to my mind is multitasking and having the data 
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available at all times. Second,(and this question will probably 
illustrate my state of non-expertise ), it's not possible to declare 
DC's relative to AS, is it? 


Code vs. Data Space 

From: Cpettus 

While the current Mac II system doesn't enforce it, eventually 
there will be Mac systems in which the data space of the program 
is protected against execution and the code space of the program 
is protected against writing. This is usually done (although not 
required) in a multitasking system, and IS required if systems 
areeto share programs across multiple tasks. The enforcement 
will be done in memory management hardware. 

The question which arises is how to tell if a particular piece 
of memory is code or data. On the Mac, it will probably be done 
by assuming that certain resources (CODE, DRVR, CDEF, 
WDEF, etc.) are executable code, while anything else is data. 
Thus, if one puts DS’s or DC’s into code resources, and then tries 
to modify them, the system will generate an unfriendly error. 
The solution? Put all data into either memory blocks allocated 
on the fly using the memory manager, or into global data areas 
referenced off of AS. The exact method for doing this is 
tremendously development system dependent, but nearly all of 
them have facilities for handling this. In most high-level 
languages on the Mac, it is handled behind the programmer's 
back, so you don't have to explicitly deal with it. 


MacTerminal 2.0 and System 4.1 

From: Bugs 

We've been having some problems getting MacTerminal 2.0 
to work with System 4.1. Has anybody else been experiencing 
the problem or haveany thots asto why? MacTerm either hangs 
or fuse bombes with various codes and there doesn't yet seem to 
be a pattern. This problem occurs on SEs and 512Es as long as 
we use the new System. Clues? Thanx. 


MacTerminal Patch 

From: Richard Scorer 

Try removing Easy Access. I think this is causing the 
problem. It appears to give a few programs a headache. 


From: Don L 

The MacTerminal bug seems to be due to accessing Ba- 
sicGlob which was not used by the system before but has now 
been changed to ExpandMem and is used. I have been able to 
fix my copy by changing the single occurrence of $000002B6 to 
$00000A78 with Fedit (BasicGlob 2» ApplScratch). This has 
been working fine now for about a week but no guarantees. 


CRT repair 

From: Power Hopeful 

Ithought someone might be interested in the final outcome of 
my blown tube (SE). I'm just about to get it back so am not sure 
of the exact details. Besides replacing the CRT, it was necessary 
to replace both the motherboard anda (logic?) chip on the analog 
board. Remember, though, that after it blew I continued to mess 
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with it and turn the power on and off many times. 


Mac SE CRT 

From: Max 

Funny thing... I installed a Prodigy SE in my Mac SE 
yesterday, and while gently sliding out the Motherboard, I heard 
this great WHOOOOOOSH! The sound must have lasted 15 
seconds. Now, all the cables had been disconnected: I was going 
by the book, and nothing had been bumped or touched. Of 
course, when the Mac was bolted back together, it didn't work. 
Atall. Further examination revealed a hole in the back of the 
CRT: the end of the tube had fractured, and gassed the tube. 
Funny. Not a bump, not a jiggle, NOTHING touched the tube 
in any way. Near as I can figure, the CRT just couldn't handle 
the thought of all the horsepower in the Prodigy board, and chose 
that moment to commit suicide! I'd be curious to hear of any 
other spontaneous SE CRT failures. If Apple intends for this 
machine to be opened (occasionally) for upgrade boards, it 
seems they have an overly fragile set-up for the CRT. 


From: Power Hopeful 
My CRT went when I unplugged the cord from the mother- 
board. I didn't touch the tube at all to my knowledge. 


Power Supply Bugs 

From: Mysteray 

I am not going to suggest that ALL problems are due to this, 
butitis worthacheck if you have flicker on the screen (horizontal 
size instability actually.) I had this problem off and on for 
several months. Then I got my SE and the 512e quit (at first I 
thought it was a problem of jealousy, but these are only COLD 
machines?). Well... the dead 512e was alive except that the 
screen raster was reduced to a thin vertical line centered on the 
screen. Аһ ha, no horizontal deflection, but the horizontal sec- 
tion, which makes the hi voltage for the CRT was fine, since I still 
had something visible *and* in focus (the line). 

Poking around on the analog board revealed a cold solder 
joint on pin 4 of J1, the 4-pin connector for the deflection yoke. 
This circuit operates at very low impedances, and thus at high 
currents. Cold solder joints can come from poor original solder- 
ing, but since this board is wave soldered, that is impossible. I 
suspect that poor contact between the pins(male & female) of this 
circuit caused local heating, enough to reflow the solder, which, 
due to deflux cleaning, had no flux to aid wetting; the result was 
a ‘cold’ solder joint. A quick resolder with a 50-watt iron fixed 
it. Now raster is rock steady. I also unmated the connector and 
retensioned the female contacts in pins 3 & 4 (uppermost ones) 
using a very small screwdriver—just to bring the two semi- 
circles closerand tighter. This should decrease contact resistance 
here, which may have caused the heating in the first place. 

This may be a possible cause when horizontal instability is 
observed, and in my case it ultimately was complete failure of 
horizontal deflection. I might add that I have 25 years hardware 
experience (1.е., tinkering since high school, but my first job was 
repairing avionics while in high school). Anyone who doesn't 
know what all this is about had best get some expert assistance. 
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But if you know where to look and what you might expect to see 
in a good or bad solder joint (mine was under the double-sided 
foam), you can save yourself days of downtime and, of course, 
some money. Good luck. Anyone needing advice on this may 
contact me, but I don't repair Macs for a living. 


From: Jim Reekes 

I wanted to thank Mysteray for his posting on May 11th about 
fixing a Mac power supply. My Mac has been with me since Feb 
84. Everything has been upgraded since then except the PS. 
Recently my screen started flickering and it seemed like a good 
time to replace it. I'm Apple certified, but don't work at a 
dealership any more. I have AppleCare to cover my repair but 
after waiting for more than 6 weeks for one to show up at my 
dealer, I decided to "do it myself". (apparently Apple is still not 
exchanging Mac PS fast enough to met demand.) 

My problem was a intermittent ‘blink’ across the screen and 
an occasional ‘seizure’ were it would shrink and get dim. It never 
dimmed out totally or shrunk to just a horz line, most of the time 
it just blinked at me. Removing the power supply and reading 
Mysteray's messages closely, I found the exact same pins on J1 
going to the deflection yoke now had bad soldering. I had to look 
REAL close to find it, in fact I was using a magnifying glass. 
There were two bad joints at J1 and two more at J2. Both of these 
connectors supply voltage for the CRT. After desoldering and 
resoldering them, everything has been fine. No more screen 
blinking! 


More comments on bad solder joints and flicker. 

From: Mysteray 

Seeing the post from Reekes leads me to believe that we have 
a hardware design problem here. I' m referring to my post of 
abouta week ago which explained locating a cold solder joint on 
the deflection yoke connector. I've thought more about it in the 
interim. I've been soldering since late 1950's and was always 
sceptical that а cold solder joint could develop by itself. They 
usually occur from poor soldering techniques. But since most 
(all?) computer boards аге now flow soldered, such things 
shouldn't happen. They can happen if the joint isresoldered with 
lousy techniques, and this is what happens when you let the Mac 
itself try to heat up the joint! 

I am convinced that the only way for my failure to have 
happened was by the connector pin itself becoming hot enough 
through increased ohmic losses due to poor mechanical contact 
in the 4-pin nylon housing crimp connector that Apple used. The 
vertical circuit that also shares two of the four pins should not be 
a problem, as it operates at a much lower current (the wire size in 
the vertical yoke winding is smaller, there are many more turns). 
But the horizontal deflection coil is much different. It has far 
fewer turns and the wire is 4 or 5 parallel strands. The DC 
resistance is below a half ohm. This makes it important that the 
losses everywhere in the circuit be kept low. The connector is 
hence a critical element. I myself can't think of a suitable 
connector of comparable cost offhand, but Molex or somebody 
else probably has. It would have been better to have directly 
soldered the yoke to the PC board, but that would have made 
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servicing by less skilled people difficult—and increased the risk 
of a human-induced cold solder joint as well. 

The best thing to do is to apply preventive maintenance by 
increasing the friction of the connector. My previous post 
perhaps was not detailed enough here, so I'll explain: Detach the 
4-pin connector to the yoke (J1)—there is a locking tab that must 
be depressed. Inside the cable part you will see female pins that 
are made from sheet metal that was rolled into a cylindrical 
shape. It will appear to be in two halves, i.e., there are two semi- 
circular parts. These must be bent *slightly* so as to make them 
closer and hence more tightly grip the male pin when connected. 
A miniature screwdriver, or an awl, will work well here. The pins 
that need this (the horizontal yoke) are the ones that are on the 
upper end when mated. Do them all actually, it won't hurt. Also, 
inspect the respective solder joints on the solder side of the PC 
board. Any side of any anomaly should be resoldered. Visually 
compare these solder fillets with others anywhere else on the 
board in case you are not sure what a good solder job looks like, 
i.e., don't have experience soldering to PC boards. 

Га like to know how many will find their horizontal flicker 
gone. If anyone is unable to do this, or is scared of opening up 
their Mac, leave me e-mail. Perhaps if enough such responses 
come in I can set up a clinic some Saturday and fix ‘em 
somewhere for $10-30, but I'd rather everyone educate them- 
selves to do such minor repairs. Kind of like opening the hood 
to check the oil and such. I want to add some caution about 
getting too near the Hi Voltage parts of the Mac. I myself don't 
discharge the CRT, since it is very well insulated from the CRT 
back to the flyback transformer. I prefer to just not get close to 
these. If you remove the analog board or CRT this MUST be 
discharged, but otherwise is not necessary. But BE CAREFUL, 
just like you don’t stick your hand into the fanblades of a running 
engine. Good luck. [my 60th line...no more time/room] 


Analog Board 

From: Dirck 

A friend of mine told me that all macs will eventually end up 
with the single vertical line syndrome. he says that capacitor c1 
on the analog board will go out eventually. apparently there are 
occasional large surges going through it and it just goes out after 
а while. it's good that it goes out, instead of something more 
expensive going out. we havea mac in surgery upstairs here, and 
were going to replace that capacitor. i'll let you know how it 
goes. 


Analog surgery results 

From: Dirck 

As it turns out, the topmost solder joint of the 4 pin connector 
had melted. this is connected toc1, so that may be why my friend 
has to replace his frequently. the connector's plastic had melted 
together. the bottom line appears to be that the two heat sinks at 
the top of the board just ain't sinking enough heat. we may try 
putting some larger heat sinks on the board, but now that we 
know what the problem is it's really no big deal to fix. beats 
paying $150 for a board swap. i wonder if any techs out there are 
just resoldering the board and charging the full fee. techs at 
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computerland type stores are just supposed to swap boards 
regardless of what's wrong, anyway. i bought a little 3 1/2" AC 
fan atradio shack which i park. on that corner of the mac's case. 
it seems to help and it's cheap. 


WMgrPort... 

From: The Cloud 

I'mfeeling acertain level of frustration about what “сап” and 
"cannot" be done...apparently if I want to use ZoomRects (and, 
parenthetically, I feel they are a valid part of the implementation 
of the Mac Interface) I have to create a window of my own, fill 
it with the desktop pattern to look like it's the real thing, and do 
my drawing in that. Kludge city. Why even have the 
GetWMgrPort available (or at least documented)? Next, we 
won't be able to do anything with files not created by our own 
programs....oranything that mighthave the “look and feel” of the 
Finder...well, enough ranting. The next product from Apple will 
probably cause me to see the error of my wrong thinking... 


Conditional Compile ‘feature’ 

From: The Toolsmith 

If you are using conditional compilation, there is a feature I 
discovered Saturday that you should be aware of. The (* ... *) 
comment form DOES NOT COMMENT OUT conditional 
groups. The code between {$IFC xx} and {$ENDC} within the 
(* *) pair WILL STILL BE COMPILED! Beware!! 


From: Lsr 

The most effective way I have found to comment out code is 
to surround it with ($IFC FALSE} ... (SENDC). This technique 
works with both kinds of comments, nested conditional compi- 
lation, etc. 


MPW Draft Printing 

From: Rick Boarman 

It seems some people are still having problems printing in 
Draft mode with MPW. Well, it doesn’t work in 1.0 nor in 2.0. 
I have a crude solution (not pretty but it works). Rename an old 
Imagewriter (like v2.3) to something other than ‘Imagewriter.’ 
Stick it in your system folder and use the Chooser to select it 
when you want to print from MPW. Be sure that you use the -q 
Draft option. Again, very ugly, but it's better than waiting an 
hour for your printout. 

MPW 2.0b1 

From: Cpettus 

In case anyone is either notan АРПА memory or has been on 
Mars, АРПА is now shipping (well, advertising MPW 2.0b1. 
Contrary to previous rumours, it WILL run on a Мас+ or SE, but 
requires 128k ROM, 1 mb, and a hard drive (which, really, it 
always did before, for practical applications). The upgrade from 
1.0.2 is $125 for the shell, and $50 each for Pascal and C; this 
includes the production version of 2.0 when it is released. 
МасАрр 1.1 is also available for $15; it “extends MacApp 1.0 to 
support the features of the Macintosh SE and Macintosh II" 
(sayeth the APDA catalog). 
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. Launch from LSC 

From: Gary Voth 

Speaking of. Launch... I’m including a Transfer... item іп 
my File menu in an application I'm writing in Lightspeed C, but 
I haven't sat down and created the C interface routine for 
Launch yet. My question is, does LSC permit an application to 
launch another program while still running under the develop- 
ment environment (i.e. using the RUN command)? Gary. 


From: Larry Nedry 
Yes you can launch to another program while under the 
development environment. Larry 


32k limit in TextEdit 

From: Mark Chally 

Like in many things, doesn't that limit go to 64k with the new 
(128k—not so new any more I guess) ROMs? Also, what 
happens when it goes to 32k? Do I turn into a pumpkin, or loose 
characters on the beginning of the TERecord, or bomb, or what? 
What's the best way to avoid any of these problems (I.E. chop 
off the front when 32k is near). Thanks in advance. (PS: I've 
never approached the limit in my application (a basic chat 
window in a telecommunications game) so I dunno). 


Mac 1 & LightspeedC 

From: Larry Nedry 

I had a Мас+ and Mac II side by side compile the same code, 
about 3000 lines, and the Mac II was done before the plus had 
displayed the first line number. Yes, it does work on the Mac II 
and IT IS FAST! 

Rumors! 

Would you'd like to believe that Apple has Stopped develop- 
ment of the Macintosh II. If you assume this your'e dead wrong. 
Why did Apple Hard wire the clock in the Macintosh II? Why 
didn't Apple use a replaceable crystal like everybody else? I 
know that Apple wants second gen of the Mac II by First QTR 
1988, thats less than two years away. Apple builds and test 
product well inadvance of anouncement. I saw a Macintosh SE 
at Apple over one year before it was introduced. It pays to drive 
by the Apple Corporate offices at lunch time. You see Apple 
ships product over to the main office about once a month. The 
guys doing this don't ship everything in the boxes that there 
suppose use. Iknow that Apple has Taken delievery of 68030's 
and 68020 (25MHZ). I know that Mr. Gasse want a suped 
Macintosh II by the First QTR of 1988. Weall know that John 
Skulley said that he wants Apple to be the first vendor with 
68030 microcomputer. 

You guys remind me of the ostrich. Stick your head in a hole 
some where, now you can't see anything there for it must not 
exist. I realize we have some important people on this BBS but 
some of you seem to think you are important enough to know 
Apples darkest secrets. I HAVE SEEN AND PLAYED WITH 
А 68030 PROTOTYPE AT APPLE. | 

There will be no 68030 based system any time in the near 
future. The ‘030 was WAY WAY preannounced to take some 
of the wind out of the sales of the 386 announcement: if it exists 
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as a real chip at all (something of which I have considerable 
doubts), it is at least a year, probably more, away from produc- 
tion quantities. The ‘020 had been a full production, fully 
ramped up, chip for YEARS (yes, years) before the Mac II was 
announced. The post which started this flurry described the Mac 
IIasan "interim machine." What's interim about it? Using an 
020? I doubt it, since the 030 is just a data sheet with 
"preliminary" stamped on it. The NuBus? If Apple has 
announced the NuBus only to replace it with some other 
architecture, they should pull the lifesupport on Apple manage- 
ment now, since they would clearly shown to be brain-dead. If 
they stick with these, then any new machine which uses these 
would hardly be a revolutionary improvement on the Mac II. 
Finally, it simply makes no sense at all from a marketing point 
of view to spend the effort Apple has to do market development 
on the II and thenkill it witha new machine. Conclusion? Some 
people are trying to play “оо hip to live,” using the industry's 
current intense paranoia and NDA-madness to score some 
points. Of course, I could be shown to be a complete fool and 
a**hole come December, but I don't think that will come to pass. 
The fact of the matter is, the II represents just about the top end 
of the technology Apple can, this year, bring to bear on the Mac 
problem. Next year, 25mHZ ‘020s, year after, “030$. December? 
New video cards. 

I have no doubt that somewhere there are ‘030s running at 
25MHz. If one is getting 1 in 10,000 yields, all you have to do 
is run the foundry long enough; further, it doesn't matter if the 
mask is full of bugs if all you are cranking our are preliminary 
samples. There is a LONG LONG time between the first 
prototypes of a chip and when it is ramped up for production. 
Remember, while Apple is a huge customer of Motorola, the 
board-level product OEMs are even bigger; if the “030 was ready 
for full production, I doubt Motorola would be holding back. PCs 
are built out of chips which are available in volume, not experi- 
mental prototypes. 

The 68030 that I saw at Apple was running at 5 (five) 
Megahertz. Probably for reliability reasons. 

Rumor has it that Apple has taken delivery of a few of 
Canon's new Color Laser engine. The same engine used on the 
Canon Color copy machines, that are actually scanners/laser 
printers combined. 

Appleis looking at using the Conner Peripherals 3 1/2 inch 1/ 
2 height 100 Megabyte drive in future versions of the SE. I saw 
an SE with one yesterday. The drives will be available for 
evaluation in August/September at $1595. If you want to buy 
5000 units per year you can probably get a contract at $1000 
each. I meant to say they will be available from Conner in 
August/September. 

System 5.0 and Finder 6.0 will be released on schedule in 
July, 1987. Finder 6.0 is multitasking. 

Finder 6.0 will almost certainly NOT be multitasking in the 
traditional preemptive rescheduling sense. If they get J*****r 
working in time, it might be a nonpreemptive system in which 
other programs can run while the foreground application (the one 
whose window is frontmost) is waiting on GetNextEvent, but 
true preemptive rescheduling will probably not be for 6 months 
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or more, and then probably only on the Mac II and future 
machines. 
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This month's MouseHole report was edited on Microsoft 
Word 3.0, starting with an almost 200k text file and ending up as 
what you read here. During the course of editing, Word ran low 
on memory 4 times (Low On Memory, Please Save and Restart), 
created 6-8 temp files that it did not remove (one was > 160k) and 
Bombed 3 times. Word 3.01 should be available to registered 
owners ... [By order of the Publisher, MacTutor refuses to print 
the following slang phrase in a family Journal: “by the time you 
read this". -Ed]..., but the date (Originally 30-Jun-87) keeps 
getting pushed back as MS finds more bugs. - Rusty 

more SE fan woes... 

From: Mysteray 

Do you notice any flicker on the left side of the CRT display? 
Like an up-down jitter. Maybe it will be more easily seen if you 
cover up the fan intake on the left side on the back. Use your hand 
to adjust the amount of air flow—the sound will increase in pitch, 
like a vacuum cleaner whose hose is being closed off. As you 
‘adjust’ the speed there will be a point where a very obvious 
ripple should be seen running up and down the screen. Is it there? 
Probably!! 

It is caused by the far field (i.e., magnetic field) of the fan 
motor being spatially modulated by the rotation of the fan 
impeller, and perturbs the CRT deflection slightly, just enough 
to be noticed. With the fan at full speed the beat frequency with 
the vertical scan rate is maybe 6-8 Hertz. If the fan speeds up the 
beat approaches zero because the frequency difference is 
smaller. 

Anyway, this wobble is becoming increasingly annoying to 
те. Тат getting used to the noise but this jitter is too much. [7 
agree. Our SE has the same problem. The fan is a custom DC job 
that uses four magnetic coils to accelerate a disk around, feeding 
air from one side to the other. Since the power supply is now 
sealed, Apple apparently chose a DC design. But they seem to be 
more noisy and interference prone than AC fans. Calling Dr. Loy 
Spurlock... after you design a battery holder for the Mac II, how 
about a new Fan design for the SE? -Ed.] 

System Problems 

From: Richard Hyman 

A small complaint concerns the strings in systems and finders 
that identify the version. Most strings are Pascal strings, but one 
of the strings in the SE system/finder has no length byte. On eof 
theold finders didn'tidentify itself correctly ( 4.2 identified itself 
as 2.2). The content of the strings isn't consistent; the new Mac 
II system/finder has changed the wording and doesn't have 
version dates. This inconsistency makes it hard to write version 
appl's that can be rather important on large AppleTalk nets with 
inexperienced users. The suggestion for this is of course that 
Apple be consistent in the use of these strings, no matter what 
standard they use. 

PRAM loses the SCSI bus... 
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From: Jim Reekes 

About five times a day I get a call from a user or dealer that 
just got our 80MB internal drive for his Mac II. Itis always the 
same exact story. “I had a system bomb and now I can't get the 
hard disk to be recognized. I've reformatted, installed new 
drivers, and even ran Disk First Aid on itand they all worked. But 
I still don't get the disk icon on the desktop." 

My response is always exactly the same. “There is a bug in 
the Mac II. Many times after a system error, parameter RAM gets 
trashed. What you need to do is hold Shift - Option - Cmd and 
open the control panel. Then reboot." I'm about to get an 
answering machine hooked up to my phone to repeat this 
message to everyone calling me for tech support. 

The Mac ll as a Workstation... 

From: Dave Kosiur 

I just spent some time talking to a few people who attended 
MacWorld's conference for developers last weekend. One 
interesting comment came out of all this - it appears as though 
Apple'smarketing people (and others?) have notthe faintest idea 
of how to market the Mac II as an engineering workstation. One 
acquaintance went so far as to say that, if the Mac IT does succeed 
as an engr. workstation, it ‘ll be because of a fluke. I think that 
the Mac II may have great potential as a engr. workstation, but I 
agree that Apple and it's approach to the dealer network aren't 
going to help. What do you think? 

[Apple's problem is that the dealer network doesn't know 
anything beyond how to turn on the machine and double-click on 
a few demo applications. There is a crying need in this country 
for some good ‘ole fashioned “No Fluff’ computer stores to 
service the more technically oriented workstation user. See our 
ad in this issue for readers to identify their favorite "No Fluff” 
computer store. -Ed] 

Geez! 

From: Power Hopeful 

Here's a laugh... I'm messing with MPW 2.0 commando 
(neat), and the Prodigy SE in my machine causes the scrolling to 
be so fast that I can’t get it to stop on any of the middle items ! 
! 

Omnis vs 4th Dim. 

From: Mick Billesbach 

I was at an Omnis developers conference last weekend and 
had achance to observe 4th dim. It certainly is slick, butacouple 
of negatives occurred to me. It definitely seemed slower to open 
andredraw screens. 4th Dim. creates separate files (icons on the 
desktop) fora lot of the components of the database. If the name 
of any of the many files is accidentally changed on the desktop, 
4th Dim. cannot find the file and behaves irrationally. [They 
should read this months feature article from Dave Rausch to find 
out how to do it right! -Ed]. 

1 meg SIMM board 

From: Wayne Correia 

Computer Partners has the nice price on 1 meg SIMM 
expansion boards. Prices start at «$300.00 each, and they have 
quantity pricing. The phone number is 714/826-9190 ask for 
Mac Mike or Dave Lawrence... 

Mac Il arrives! 
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From: David Smith 

I got my Mac II today! I ordered about the time of the Apple 
developers conference so that should give you an idea on the 
backlog. I also ordered two video cards, b/w and color monitors, 
80 meg disk and memory expansion. What I got was a bare bones 
get running system. The Mac, b/w video, one video card. No 
disk, no memory upgrade, not even the video card expansions. 
So you can expect a minimum shipment. Fortunately the Dat- 
afram 40 xp works just great with it! One big problem: MacWrite 
doesn't work!! Fortunately someone on Apple Link sent me an 
underground copy of the yet-to-be-released version 4.6. (Inci- 
dentally, you can reach me at D0435 if you have an Apple Link 
account. Always fun to get mail!) 

Commando 

From: Rick Boarman 

MPW's Commando is slick!! Type in “commando «any tool 
name>” and see what you get. It’s a graphic interface overlayed 
on top of the tools. There’s a new chapter in the manual 
explaining how touse itand how to create your own commandos. 

The only things lacking in commando are commandos for 
commando and saving defaults. It’s a pain to always type in 
“commando” and whatever tool you want. It’d be nice to just 
type “commando commando” and get a list of all commando 
tools to select from. Also, I wish thatif you pass in the parameters 
for the tool, commando would set up all the right defaults so you 
wouldn't have to. This is areal pain to do when multiple files and 
folders are involved. 

Calling Commando 

From: Chief Wizard 

There’s a faster way to call commando for a particular tool. In 
addition to typing ‘commando toolname’, you can type 
‘toolname...’, where the ‘...’ is the single character elipses 
(option-;). 

Another tip: If you hold down the command and option keys 
when you hit the button in commando that activate the tool, the 
command line for the tool is written to the worksheet, but isn’t 
executed. This way, you can re-execute the command (and even 
modify it), without the overhead of going into Commando every 
time. 

Favored Hard Disk 

From: The Toolsmith 

For anybody who is interested, I’ve had my Jasmine 80 for 
about 2 months now and ZERO problems. Fast as the 40XP I use 
at work, too. They seem to be for real... 

From: Mike Steiner 

I've had very good experiences with my 80 meg CMS. Good 
experiences as in not blowing up, no bad blocks, etc. It just sits 
there and does its job. I've had it for only one month, though, so 
I can’t give it an unqualified recommendation; however, if it 
behaves the way it has been behaving, it deserves a high recom- 
mendation. Besides, we have their tech support person here on 
the ‘hole (Reekes) in case something does go wrong. 

[CMS also has drives up to 320mb for the Mac, and they work 
on the Mac II, unlike Apple’ s yet to ship 80 meg drive!- Rusty] 

Mac SE Hard Disk 

From: Wayne Correia 
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Today, a customer came in to our store with a new Mac SE 
with the internal MINISCRIBE hard disk mech. It was dead, but 
Idiagnosed itin afunny way. The RED in-use light blinked *** 
— *** which is ‘SOS’ in morse code!... 

SE Ram Failures 

From: Wayne Correia 

If you have a problem with RAM, you will geta SAD MAC 
screen with a code. to isolate a faulty SIMM on a Mac SE, refer 


to the chart below: 
0000000Е SIMME 1 000000ХХ 
0000000E = SIMMH2 0000XX00 
00000002 SIMM']1 000000ХХ 
00000002 5ІММ82 0000XX00 
00000004 SIMM!3 000000ХХ 
00000004 СІММЕ4 0000ХХ00 


XX inthechart above indicates a non-zero digit in one or both 
ofthe positions. An unreadable code often indicates that SIMM 
#3 or #4 is at fault. 

Filter Procs 

From: Chief Wizard 

If you pass a pointer to a procedure to a routine (i.e. @myFil- 
ter for ModalDialog, or 9 myResume for InitDialogs), then that 
procedure MUST be at the outermost level of your program. 
Here's why: 

Most current (maybe all) Pascal compilers use address regis- 
ter A6 asalocal stack frame pointer. This pointer lets the routine 
access its own local variables as well as the parameters passed 
into the routine. 

Now, since a procedure (let's call it Procedure B) that is local 
to another procedure (say, Procedure A), can access the outer 
procedure's variables and parameters, extra steps have to be 
taken. For example, let's say you have the following structure: 


PROCEDURE A(paraml : AType; param2 : AnotherType); 
VAR — (some variables local to procedure А) 
PROCEDURE BCparam3 : Type3; param4 : Type4); 
VAR {variables local to procedure B) 
BEGIN 
END; 
BEGIN 
END; 


Procedure A uses register A6 to access its parameters and 
local variables. Procedure B also uses register A6 for ITS parms 
and local variables. In general, when one procedure calls 
another, A6 gets saved and restored, so each procedure has its 
own A6 value. 

The catch is this: procedure B has to be able to access the 
params and local variables of procedure A because of Pascal's 
scoping rules. So, the Pascal compiler passes procedure A's A6 
register to procedure B as an extra parameter. This way, proce- 
dure B has its own A6, but it also has procedure A's A6, because 
it was passed to B as a parameter. 

This causes procedure B to have one more parameter than you 
specified in the procedure declaration. AND, since the Mac 
ROM is expecting to calla procedure with a certain set of parms, 
it doesn't pass the extra A6 parameter. This trashes the stack, and 
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causes a crash. 

The net effect of all this is that you have to put your filter procs 
at the outermost level. Annoying, but not too bad. 

Word printing problems 

From: Jim Reekes 

Make sure you turn RAM CACHING OFF with Word 3.0 !! 
You'll not be able to print with the System 4.1 RAM CACHE. If 
you want faster speed, use Word's internal caching system. 


Keyboard Polling 

From: The Cloud 

I need to know exactly how to poll the keyboard each 
time through the main event loop (alon with my cursor- 
checking) so that if JUST the option key is down (and the 
cursor is in a particular region), I can change it. IM says that 
the only way to do this is to call GetKeys... but this returns a 
packed boolean array... 

Option key 

From: DON 

You can easily check for a depressed option key in your 
event loop by simply looking in your event record. The 
modifiers word in your event record contains a bit which will 
be set if the option key is down. Do a logical AND on the 
modifiers word with the predefined mask called (cleverly) 
"optionKey" (equal to 2048 decimal) to see if the bit is set. 
Note that you need to be receiving null events to check for this 
continually during a null event. 
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SuperPaint Update 

From: David W 

Silicon Beach Software just released an update to Superpaint 
in order to fix a problem Superpaint has with the most recently 
released drivers (4.0) of the LaserWriter. The new version is 
1.0р. You can obtain a copy either by mailing a disk to Silicon 
Beach Software or use the patching software that I just posted on 
MouseHole Download. If you try to use the patching program 
FOLLOW THE INSTRUCTIONS carefully. Among other 
things you must first place your copy of SuperPaint on to a 400K 
floppy; it won't work with an 800K floppy. Also you will need 
any version of the installer program that Apple distributes to 
upgrade system disks. 

[The following post summarizes the Editor’ s feelings on the 
issue of piracy and pre-release software, which recently became 
a hot topic on the Mousehole over Steve Brecher's SuitCase 
program. -Ed] 

Piracy & Beta Software 

From: David Sternlight 

It's not pious to say that taking someone' s property without 
their permission is theft. (і.е., TSPWTPIT). It's the law. If A 
is the beta tester and B is his friend, whether B knows he has 
received stolen property or not doesn't change the facts that B is 
legally liable. The profit, by the way, is in knowing about it or 
using it. That's what "intellectual property" is all about. You 
don't have to make money from someone's property obtained 
without permission for it to be theft. 
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If a developer wants the "benefit" of people seeing his beta 
and maybe buying the release, he has the option to circulate his 
beta. If he chooses not to do that, and imposes non-disclosure or 
non- distribution limits on it, then TSPWTPIT. You can't make 
it o.k.; only he can—it’s HIS property. 

I believe that TSPWTPIT. I am under the impression the law 
says the same thing. No amount of rationalization will change 
this. Itwon'tdotoargue why itis a good thing to take someone's 
property without permission. It won't do to talk around it. The 
only LEGAL way to get someone else's property is if they give 
it to you, or give someone else permission to give it to you. People 
miss this point with software because a copy seems not to affect 
the original; except for the cost of the medium, it seems cost-free. 
However, software is intellectual property and the law specifi- 
cally recognizes that in this case, as with pirated tapes, passing on 
acopy isillegal. You are allowed to make a single copy for your 
own archive use under the copyright law. You are not allowed 
to give acopy to anyone else without permission. Beta orrelease 
version, it makes no difference; copyright is copyright. The law 
doesn't say, "Oh yeah, if it's a beta (or a pilot or test tape of a 
copyright song) THEN the law doesn't apply." 

Code Length/Time in Sorting 

From: Geoff Bryan 

It is very difficult to generalize from length of code to length 
of execution time. The real issue is the quality of the algorithms 
you choose. For example, here is some code for a short but 
extremely slow sorting routine known as a "bubble sort": 


bubbleCitem,count) /* bubble sort */ 
char *item; /* item = ptr to char array */ 
int count; /% count = no. of elements */ 


register int a,b; 
register char t; 


forCa=1;a<count; **a) 
een жылы 


if item[b-1] > item[b) 
tz item[b-1]; 


item[b- 1)2item[b]; 
item[b]*t; 


) 
) 


Even using register variables to speed things up, this has 
rightly been described as one of the worst sort methods ever 
conceived. The amount of time it takes to sort goes up by the 
square of the number of elements in the array, so the time gets 
much worse with bigger sorts. One of the better sorting algo- 
rithms is the “Quicksort” invented by C. A. К. Hoare. It takes up 
a bit more code, but for an array of 100 elements, can complete 
its work with only 1/5 the number of comparisons and far fewer 
exchanges than the bubble sort: 


qsCitem, left,right) 
char *item; 
um left,right; 


/* quick sort */ 


register int i,j; 
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cher x,y; 

i=left; 

ј=гідћі; 

x=item(Clefttright)/2]; 

/* ке element = comparand */ 

do 

whileCitemlil<x && i«right) i++; 
whileCx<item(j] && jp left) j-; 
ifCic=j) ( 
y=itemlil; 
itemli J=item(j]; 
item[j]l=y; 
i++; 
) 
whi leCi<=j); 
if Cleftcj) 
asCiten, left, j); 
if Ci«right) 
qsCitem, i,right); 
) 

For a little more code, you get a lot of performance improve- 
ment. Thus it's hard to “judge a book by its cover” in predicting 
execution speed from code length. (Examples from H. Schildt, 
“Advanced C.") 

Sorting & Piracy 

From: Laser Dolphin 

Although it is impossible to generalize speed from code 
length, there is one rule which is universally true: if you “ип- 
wrap" loops into a series of equivalent, noniterating statements, 
thecode will be both longer and faster. Jim Reekes alluded to this 
when he spoke of the number of clock cycles needed to do 
branches. Bubble sort is more clearly written in Pascal pseudoc- 
ode, thus: 


For scan := 1 to arraySize-1 do 

For index := 1 to arraySize-scan do 

if erreyElement[index] < erreyElement[index*1] then 
SwapCarrayE lement [ index], errayElement( index* 11) 


This code shows clearly the meaning of the procedure, minus 
the coding details. The bubble sort must scan the array one less 
time than there are elements in the array; for each scan, the inner 
loop compares adjacent elements and swaps them if they are out 
of order. In the example given, the lesser elements are thus 
bubbled down, one step at a time, to the bottom. At the end of 
each scan, one more element is ordered at the bottom of the array, 
which explains why the inner loop ends at arraySize-scan — this 
marginally speeds up the process by not sorting stuff already 
sorted. 

Bubble sort is of order n^2 — that is, the time to execute is 
proportional to the square of the number of elements to be sorted. 
It is very simple to write, but is no good for more than about a 25- 
element array. It is frequently taught to beginning programmers 
because it is so easy to understand. Quicksort, by contrast, is 
exceedingly fast on average, but is difficult to understand, being 
a non-intuitive and recursive algorithm. 

I use bubblesort to sort a 24 element array of records in a 
program I wrote in MPW Pascal, and it causes a BARELY 
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perceptible delay in program execution. If the array were any 
larger, I would abandon bubble sort. The records consist of a 
Str255 and an INTEGER. 

David Sternlight, there is no question that you are 100% right. 
Copying software without authorization from the copyright 
owner is illegal. However, copyright owners should recognize 
that distribution of beta copies, properly marked and properly 
guarded against long-term use, is helpful to sales of the release 
product. People should not have to buy software sight-unseen. 
Moreover, Microsoft BASIC became the de facto standard only 
because Bill Gates's punch tape of Altair BASIC was thoroughly 
pirated. Bill Gates's famous anti-piracy letter completely ig- 
nored the fact that his success was owed entirely to piracy. The 
pirates were wrong, but so was Gates. Of course, the pirates, as 
well as Gates, were all teenagers then; no doubt they know better 
now. [10046 market share obtained by 100% pirated copies = 0% 
return on investment + 100% fame and glory. Adjust balance to 
suit. Poor and famous, or richand unknown. Bill Gates obviously 
found a balance he could live with. -Ed] 

Author's apology 

From: SpUd PoTatO 

Okay, okay, stop bugging me! my program (the new “Font/ 
Fkey/etc. Sampler") has bugs in it! Ihereby give a public apology 
for those bugs, but give me a break; I've got to work just like 
everybody else! Look for a debugged version on your favorite 
BBS in a week or so... 

By the way, contrary to popular belief, I was NOT part of the 
Microsoft Word 3.0 Development Team... 

т in hog heaven! 

From: Bugs 

Apple is shipping Mac П color monitors and I got mine today. 
It gives new meaning to “totally awesome". What you can do 
with this machine... at this late date I' m still amazed! 

Microsoft Word 3.01 

From: Jim Von Schmacht 

Speaking of Word 3.01... I received mine on the 1st. Neat 
stuff, all the problems I was experiencing are fixed, it runs faster. 
It still leans a little to far toward an IBM interface...oh well... 

Byte Benchmarks off mark 

From: Frank Henriquez 

I typed in two of the benchmarks that Byte used on the Mac 
II article, the Fibonacci and the Sieve, and compiled them using 
Lightspeed C (obviously the resulting code was not optimized for 
the 68020 and the math operations went through SANE). On the 
Mac II, the Fibonacciran in about 40 seconds (not 83.70, as in the 
Byte article). I'll have to recompile the Sieve, because it ran too 
quickly to time...(under 1 sec). I don't know what the fine folks 
at IBM Slave Magazine (aka "Byte") were thinking / doing when 
they were running these benchmarks on the II, but they should be 
made poster children for the Drug Free America project. 

HyperCard 

From: Jim Reekes 

I've been checking out HyperCard 1.0, the new wonder 
program from MacPaint's Bill Atkinson. It reminds me of a 
fancier version of the old Habadex program from '84, only 
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bigger. Including the sample files, it's nearly 3MB! The help file 
(which is the best *stack") is nearly 600k. Sure it's a beta copy, 
but I don't understand it's application. Maybe I'm missing 
something. I don't feel that 3rd party software developers need to 
worry about Apple bundling it with the Mac. 

MPW Assembler 

From: Geoff Bryan 

I spent the money to “upgrade” from the beta to “final” 
version of the MPW Assembler manual. As far as I can see, (1) 
none of the mistakes I had noticed in the first manual were 
touched, and (2) one or two new ones were introduced. (This is 
for version 1.0, by the way.) What gives? 

MPW manual 

From: Power Hopeful 

The new manual has an index! 

Slow SE hard disks 

From: Jim Reekes 

The slow internal 20MB in the Mac SE is not Apple's fault. 
Well, in a way maybe, but it is a slow (85ms) Rodime 652. With 
a fair amount of file fragmentation, I don't doubt you've noticed 
it’s sluggishness. 

Cursor and CopyBits 

From: Leslie 

Has anyone seen their cursor disappear when a call is made to 
CopyBits? I’m using Lightspeed Pascal, and when I call Cop- 
yBits to erase a bitmap (copying a bitmap to itself using srcXor) 
the cursor disappears then reappears when the call is complete. 
The bitmap is offscreen and the cursor comes from aresource file 
and is visible prior to the call. 

From: Lsr 

I have noticed this happening also. Normally, Quickdraw 
will not obscure the cursor unless it is drawing to the screen. 
There must be low level routine somewhere that is not checking 
for drawing on the screen before hiding the cursor. 

Mac Il memory 

From: Palomar 

I'd be real careful on Mac II memory. Some people here got 
SIMMs (120ns, I believe) from a local chip dealer and they didn't 
work; nor did the second set. We bought the Levco ones, which 
are not as cheap as some quotes I’ve heard (even developer 
priced), but are much cheaper than Apple’s. Most important, 
they worked the first time. I would not write a check for a grand 
or $800 or whatever unless I personally took my Mac II in and 
installed them. (You don’t need a monitor, particularly if you 
make your startup program on the boot floppy a SysBeep loop) 
Incidentally, I got some video RAMs from an unknown source, 
which turned out to be flakey. One Mac II now has the official 
Apple kit, the other ones from a vendor in the City of Industry and 
both work fine. 

MacsBug for 4Mb Mac 11 

From: Palomar 

I ended up with 4Mb on my Mac II, but the MilkBug with 
MPW 2.0b1 came with only 1,2,5, and 8Mb versions (yes I plan 
to get the real Mac II version of TMON when it comes out...) 

Iended up comparing (in C) the 2Mb and SMb and producing 
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a common subset; wherever it was 001F and 004F, changed it to 
003F. My program wouldn't make any changes unless there was 
a difference between the two files. 

Here's a little MPW tool to produce a 4 Mb version, by 


changing 
001Ехххх 2 Mb version 
and OO4Fxxxx S Mb version 
to 003Fxxxx 4 Mb version 


There's one other difference that I guesstimate a middle value 
for; turns out it's only the version time (offset 0x3058) which 
differs by 12 seconds for the two versions. 

No guarantees that this is the recommended way to go, but it 
seems to work just fine... 


/* BugPatcher.c: Synthesize 4Mb MacsBug for Mac II 

July 1987, by Joel West, Palomar Software, Inc. */ 
®include <stdio.h> 
typedef unsigned char ubyt; 
typedef unsigned short HalfWord; 
/* two 16-bit 1/0 functions; 

getwC) does 32 bits on MPW C */ 
"define gethw(stream) (Ctmp=getcCstream)) == EOF ? EOF : V 
(Hal fWord CC Cubyt ) tmp )<<8 + Cubyt Jge tcCstream)) 
define puthwChw, stream) CputcC(hw)?8, stream), putc(hw&255, 
stream?) 


nainC) 

( FILE *fd2, *fd5, *fd4; 
int с2,с5,с4; 
int cnt = 0, tmp; 


fd2 = fopenC“MPW ONE:Debuggers:Mi lk2MB^, “г*); 
fd5 = fopenC^MPW ONE:Debuggers:Mi lkbMB^, *r^); 
fd4 = fopenC^HD:Mi lk4MB^, "w^); 


while ((c2=gethw(fd2)) != EOF) 
(АҒ (с2 == (c5=gethw(fd5))) 
puthw(c2, fd4); /* vote consensus */ 


else 
( printfC“Offset 0х%.4Х; 2MB: ZX; 5Mb: 3X^, cnt, c2, 
c5); 

if Сс2==0х IF && с5==@х4Р) 
puthwCOx3F, fd4); /* known difference */ 

else /* the only other diff is the time */ 

( c4 = (с2+с5+с5) / 3; /* weighted ave */ 
printfC^; guess: #Х\п”, c4); 
puthw(c4, #04); 


printf C^An^)5; 
cnt += sizeof (short); 


) 
printfC^A total of £d bytes were merged\n”, cnt); 


‘The Debugger’ and TML Linker 

From: Pkbrown 

Steve Jasik’s debugger docs state that “the first line of a 
*. MAP' file produced by the TML Pascal Linker contains a 
comma. This bothers the debugger." 

Itook his advice to heart about patching the offensive code in 
the Linker. I had to because I’ve been using the TML Linker with 
my V1.0 MDS for quite some time now. The problem is this: 

1. The first line placed in the “.Мар” file is as follows: 

TML Systems, Inc. 
The comma above crashes the system. 


© The Essential MacTutor, Vol. 3 


2. The Linker's code that inserts the string in the output 
file is in the code 001 resource. 

3. The embedded string is at “CODE0001” + $063C. 
Changing the comma to a space works fine. 

4. Using MacZap, search for the first occurence of the 
‘TML Systems, Inc.’ string and change it in the ascii 
side of the sector buffer window. In version 2.0 of the 
linker, the comma occurs at a file offset of $4C1C. 

The debugger looks good; it's a little slow in drawing all it's 
windows if you're stepping through the code of a long proc, 
especially in the Mac ROMs. 

hmmmm 

From: Dave Kelly 

Seems to be some delay in Zedcor finishing their editor, but 
I was told by someone today that they are starting to ship 
tomorrow. AssoonasIget4.0T'll posta message here for anyone 
that might like to know (especially if you are waiting for it). By 
the way, check out sept. MacTutor for info on how to figure out 
the size of the screen being used while in ZBasic. This might be 
of interest to some of you. Dave 

ll beep sounds 

From: Macowaco 

Hey the beep sounds are starting to appear for the II. The latest 
batch contains a road runners meep-meep, 2001’s “dave” and 
Monty Pythons’ “SPAM!” among a ton of others. Great stuff. 
Problem is I can’t decide which one to use. 

Beep 

From: James Murray 

Use “5РАМ!”, 

DTB 

From: Jim Reekes 

The mouse definately behaves differently when connected to 
the keyboard instead of the Mac. I recommend not chaining the 
mouse off any DTB devices. 

TORX 

From: Dave Kelly 

Ok, I've had conflicting stories about which size TORX 
opens the Mac. What size is it, 10 or 15??? I too have some video 
deflection that I would like to open up and take a look at. So... 
where canI get the TORX screwdriver I need and how much will 
it cost? I'd like to do this right away. Thanks Dave 

TORX 

From: Richard Clark 

According to Jim Magner (a local repair guy), Snap-On tools 
sells an extra long (2 foot!) TORX T-15 screwdriver for $7.95. 
All you have to do is call the local Snap-On number in the phone 
book, and one of their trucks will come to your door. Pay the nice 
driver, and you get your screwdriver. 

P.S. I have seen these screwdrivers — they're perfect for 
opening a Mac. 

Memory Upgrades 

From: Richard Hyman 

Regarding the 512E upgrade, the Dove upgrades and others 
do have problems with future expansion. I, however, have found 
Dove's telephone support to be very good. Dove doesn't sell 


591 


directly, so I went through distributor in Eugene called TSI, sales 
rep is Jean Sorensen. With little excuse, like hoping to sell more 
units to people in your company, she will give good prices on the 
Doves. Figure on $119 fora 1M, and $330 - $350 fora2M. SCSI 
ports available for about $70 more. TSI's support is also very 
good. I had a bad board when upgrading an old 128K Mac to 1M, 
and they sent me the new one via 2nd day UPS with no additional 
shipping charges to me. TSI’s phone number is 1-800-874-2288. 

Mac Menu Manager 

From: Mark Chally 

Well, in my opinion, the Mac Memory manager is a bit of a 
kludge anyway. Having an application that does real-time mo- 
dem gaming, I find it particularly dismaying that there doesn't 
seem to be a good way to do any drawing to the screen while a 
menu is down. The menu manager does some really scary stuff 
past my understanding, and I just wonder what's gonna happen 
when we have a truly multitasking Mac and one program wants 
to draw when another program has a menu down! My guess is 
the menu manager gets "fixed" real soon now. I'm on the brink 
of hitting Developer Support about it, but I don’t know what good 
it will do—»it'd take a big re-write for the manager, and/or a big 
re-write on my part to allow drawing while menus are down. (Ву 
the way, try posting an event while the menu's down and you get 
a nice surprise—zappo, just like a roll-up blind, up goes the 
menu.) 

Coprocessor Errors 

From: Randy Saunders 

I have started to have an odd problem with my Mac. When 
you first turn it on it boots up and displays the desktop. If you do 
absolutely nothing in about 5-7 minutes it bails into MacsBug 
with a coprocessor error. Bang, you are dead. If you hit reset - 
Sad Mac. Wait 3-5 more minutes and hit reset => success, and 
many happy hours of computing. I have an exhaust fan and I 
notice that the problem occurs when the exhaust air is between 78 
and 85 degrees F. Has my Mac caught a cold? My normal 
operating exhaust temp is 92 degrees F. I have opened it up and 
reseated every chip in the assumption that the problem is poor 
seating in a socket until some part expands from the heat. No 
change. Any other suggestions? Anybody else ever had this, or 
is the schrunken screen the only popular failure mode? I don't 
want to have to get a new digital board just because I can't figure 
out what's wrong with this one. 

Temp-sensitive component. 

From: Laser Dolphin 

Randy — this is just a guess, but it does sound like some 
component on your power supply has gotten temperature sensi- 
tive. Ionce had a similar problem, except the problem was on the 
motherboard. My internal drive would only work when the Mac 
was hot, so I left it on 24 hours a day, until the component got so 
bad that it wouldn't work at all. Intermittent problems are a real 
female dog. Good luck. 

power supply 

From: The Atom 

A friend has a 512 (upgraded from 128) that has suddenly 
died. When you turn it on, nothing comes up on video(black), and 
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the drive whirs some. If you listen close you can hear some 
popping noises (quiet) inside. I opend it up and can't see any 
components that look blown, anyone know what I should look for 
on the power supply. / video board? 

Power Supply Revisited 

From: Dave Morris 

My Mac + has the original 128K PW. When I noticed some 
screen shaking, I looked at the yoke connections. They had 
crystallized. Some resoldering fixed that right up. Later I noticed 
that my PRAM memory was spastic. The clock would come up 
scrambled, and Mouse set to slow speed etc. New battery did not 
help. Just looked at the battery holder connections on the power 
board. They also were cold. Re-soldered and now all is well. If 
you suspect any video or clock problems, resolder the connec- 
tions on the power supply board before you go to the Apple 
dealer. You can save a bunch of money!! 

Using a 68851 

From: Palomar 

You gotta Mac II? There's a custom HMMU in it in one of 
those huge 48(?) pin square sockets. Go to Radio Shack and buy 
an IC extractor. Go to a Motorola distributor, plunk down $600 
and wait 2 months for the 68851. Pull out the HMMU and put in 
the (16 MHz) 851. Now if you have a disk with A/UX on it, you 
can boot A/UX. If you have a disk with the Mac OS, you can boot 
it just fine (I do it all the time.) 

Given the price and availability, I assume Apple will be 
bundling the 68851 with A/UX, or no one would ever be able to 
get one. I haven't seen any indication that anyone else would 
want one any time soon; don't forget, the Mac OS won't require 
an MMU as long as the majority of the installed base is 68000 
with no MMU available. As for HMMU in 32-bit mode, that's 
a hardware question and I'm a software person. On the other 
hand, I do know that they’ ve downplayed the 32/24 traps between 
the draft Paris docs and the final MPW 2.0/IM Volume V. The 
current thinking is that an application NEVER changes the bit; 
it’s up to the OS to decide which mode is appropriate. Joel West 
Palomar Software, Inc. 

Imagewriter ІІ Mashed! 

From: Macowaco 

Egads! I just totally trashed an ImagewriterII! It was printing 
like mush and no matter what I adjusted or changed it would still 
do a poor print (even in high qual). So I pulled the head and 
cleaned it. It was pretty bad all right, but when I carefully tried to 
replace it I crushed two of the teeth in the plug that accepts the 
heads’ card. Any ideas anybody? Yeah, I know the whole head 
assembly has to be replaced, so does the rear right fender on my 
Honda. 

*eee*** and 65881 

From: Rusty Hodge 

Well, does Juggler «oops, erase that> work any better with the 
PMMU? 

LaserWriters & Margins 

From: Ross Yahnke 

Margins on legal sized documents printed on the LaserWriter 
are a real problem; even if you do select the “Larger Print Area 
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(fewer downloadable fonts)" print option you still get 1 inch 
margins of blank space around the whole document, which is 
really unacceptable in a lot of situations. Question 1: Is this due 
to memory limitations of the LaserWriter? Question 2: If so, will 
there ever exista way to increase the memory of the LaserWriter? 
Question 3: Will any of the new, rumored, laser-based printers 
solve this problem? For Apples sake, I hope soor they should kiss 
a big section of the business market bye bye. 

popUpMenuSelect 

From: Jeff 

Does anyone know how to use popUpMenuSelect. Му copy 
of inside Mac Vol. 5 makes no mention of it. I tried to use it with 
a regular text menu and had no luck. I saw a new constant 
declared in the interface files mPopUpMsg = 4; A new message 
for MDEF's? A little advice from someone in the know would be 
much appreciated. Thanks. 

Popup Menus 

From: Lsr 

PopupMenuSelect takes 4 parameters: menu, top, left, and 
item. menu is a menu handle, top & left define a point in screen 
coordinates, and item is an item number. The MenuManager will 
try to place the topLeft corner of item at the point you specify. It 
will make the menu scroll if necessary to do this and still keep the 
menu on the screen. In order to implement a popup menu, a new 
message was added to the protocol that a defproc must under- 
stand. The number is 3 (not 4 as listed in the MPW interfaces). 
The purpose of the message is to have the defproc define the 
rectangle in which the menu will appear. [See this issue' s article 
by Steve Sheets for an example of how to create a PopUp menu 
in his Color Life. Also, a simple proc for identifying color 
quickdraw machines. -Ed] 


SysEnvirons 
From: The Cloud 


Okay, I give up. How do you check to see if the SysEnvirons 
trap is present without using MPW and “linking with the .obj glue 
file"? I want to be able to use the trap, or barring that, at least 
definitively determine that it isn't there, from Lightspeed... 
Making a LS library from the glue file doesn't work...some code 
snippets would be appreciated. Thanks— -k 


AAAA 


From: Lsr 

Tech Note 129, gives the code. First test for 64K ROMS or 
later. If you have 128K ROMs or later, then do a get trap address 
on 'SysEnvirons' and compare the address with that of the 
"Unimplemented' trap. If they are not equal, then you have 
"SysEnvirons'. The Tech Note code is in assembler. In that 
language, you get the 'SysEnvirons' address with: 


MOVE.W #$90,D0 
. GetTrapAddress, NEWOS. 


You get the ‘Unimplemented’ address with: 
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MOVE.W s$9F,DO 
. GetTrapAddress,NEWTOOL. 


The point here is that 'SysEnvirons' is an OS trap and 
‘Unimplemented’ is a Toolbox trap. (For more info on the 
distinction, see Inside Mac volume 4.) 

Uh, right.. 

From: The Cloud 

The tech note *does* spell out the way to do it —in ASSEM- 
BLY! My problem is a high ignorance quotient when it comes to 
diddling with addresses from Pascal... Thanks for the e-mail. - 
k 

AAAAA 

From: Lsr 

If your language supports INLINES (as does MPW), it is easy 
to define INLINE functions that return the desired low memory 
globals. For example, in MPW Pascal: 

FUNCTION GetWordxxx: INTEGER; INLINE $3EB8, $xxxx; 

will define a function that returns low memory global at 
location $xxxx. (If you change the first hex number to $2EB8, 
then the function will return a LONGINT.) 

LSC & GetTrapAddress 

From: Ross Yahnke 

Greetings from muggy Madison, Wisconsin! I'm working on 
a game type program using LSC, and it's to the point now where 
Ineed to speed it up alittle. I want to do inline assembler trap calls 
using GetTrapAddress. MacTutor had a good Pascal article on 
this by Mike Morton in the August '86issue buthe made acryptic 
comment, “...many С compilers pass parameters differently than 
ROM routines do. Some C compilers allow you to choose the 
method of parameter passing; this willallow you to dispense with 
assembler altogether and just call the routine with a pointer (ask 
your nearest C guru how to do this)." Socould someone out there 
show me an example? Many thanks in advance! 


Indirect Toolbox Calls 
From: Gary Voth 


Ross: What you want to do is slightly complicated by the 
different calling convetions of C and Pascal. While C makes it 
easy to call a function indirectly, Lightspeed ALWAYS makes 
indirect calls using C stack discipline, so a glue routine is 
necessary. Make sure you check out the new information about 
GetTrapAddress on page IV -234 of Inside Macintosh before you 
proceed. In C a function pointer may be declared in this fashion: 

int (*myfunction) (); 

Note that the parentheses are necessary for correct grouping. 
If instead you wrote: 

int *myfunction (); 

you would be declaring a function returning a pointer to an int, 
which is not the same thing at all. If myfunction pointed to a C 
function you could call it indirectly by writing: 

(*^myfunction) (arg1, arg2, etc.); 

However, if myfunction pointed to a Pascal function (like the 
Toolbox routines) you cannot call it indirectly using the above 
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method because Pascal stack discipline will not be enforced. 
However, Lightspeed has a built-in routine, CallPascal, which 
can do the job: 

CallPascal (arg1, arg2,...argn, myfunction); 

Note that the function pointer is always the last argument to 
CallPascal. Of course, you can declare your own function which 
uses a single inline assembly instruction to call the Toolbox trap 
and not use pointers at all. Assuming that trap add contains the 
address of the Toolbox trap TEnew you might write a “psuedo” 
function: 


pascal TEHendle OurTENew(destRect, viewRect); 
Rect  destRect, viewRect; 


57 (*trap_add) С); /* global ptr to TENew() */ 
asm 

JSR trap_add | 

E^ TENew 


) 
Note that the C compiler has taken care of setting up the stack 
and returning the proper value for you. Good luck. Gary. 


Pgmkr printing 

From: Macowaco 

I'm trying to print with Pagemaker 2.0 using either a МасП 
or an SE with an IW II. It doesn't seem to want to do the high 
quality printing. It prints but it ain't high quality even though it 
is bidirectional 


PageMaker Printing problems 

From: Laser Dolphin 

PageMaker 2.0 sometimes returns PostScript errors that are 
quite mysterious. The problem seems to be insufficient memory 
on the Mac (not LaserWriter) system heap. The solution consists 
of removing memory hogs like CheapBeep, Tops, and the 
screenblanker that pretends it’s MacsBug, as well as printing 
pages individually or in small groups. Pages with 300 dpi scan 
graphics most often cause this problem. Some combination of 
the solutions suggested above has always worked to get around 
the problem for me. 

PM 2.0 

From: Mike Steiner 

Aldus has admitted that 2.0 doesn’t support the Imagewriter 
properly and that they are working опа fix for it. Ihaven’t spoken 
to them in a while, so the fix might be out by now. I do know that 
the current version being shipped is 2.0a. I have no idea what 
differences the alpha adds to 2.0, but I plan to call Aldus 
tomorrow to find out. [It fixes the imagewriter problem and costs 
$10 to upgrade. -Ed] 

RSG, version 4.0 

From: Peter 

Saw a demo of RSG, version 4.0, last night. It really looks 
great. lots of new & improved features (though really if any 
program is worth $495 is a question). Free if you bought version 
3.0 after June 1st - otherwise $75 upgrade fee. It'll be ready in a 
couple of weeks. 
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The Rumor Board 

AAAAAAA 

Before they had me sign on a stack of bibles, I had some 
information about HyperCard (nee WildCard). One thing that is 
100% definite is they’ve planned to bundle it all along, and 
briefed their sales staff several months ago on why they will be 
doing so. 

Bundling 

Well, I hope they know that current owners of new machines 
are going through life unbundled and plan to correct the situation. 
Get my drift? 

Laptop Mac 

A source high up in Apple development has related that the 
Laptop Mac is very much areal thing. Seems that they now have 
the cases in foam. In other words, they’re working on final case 
design. Expect to see it in about a year... Also, the high end 
laserwriter is definitely color. The small laser may be out sooner 
then expected, and the BusinessWriter may be also out soon at a 
price of $1295. (Providing Toshiba can get them here). 
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Га rather Switch than Find! 

From: Richard Clark 

First, Apple *will* be sending MultiFinder / HyperCard to 
developers "as soon as [they] get the disks duplicated". How- 
ever, Apple has changed the rules *again*!! I have a really nice 
piece of software written that takes advantage of Switcher's 
"background tasks" (David Smith, are you interested?). So, just 
for kicks, I tried it out on a beta copy of Juggler. No soap — it 
bombed *big*. Apparently Apple has produced a product which, 
from an application's point of view, claims to be Switcher but 
without Switcher's handy hooks for developers. 

The kicker is this: Apple has fully documented Switcher (via 
the "Switcher Developer's Kit" (aka "Inside Switcher") from 
APDA), and some other developers have taken advantage of 
Switcher's special features. But, since MultiFinder gives all of 
the same indications to a program as Switcher would, if you try 
to use these features, La Bomba! (By the way, this kills part of 
Microsoft Word. Version 3.1.1 anybody?) 

[Apple has indeed sent out System 4.2a4, Finder 6.0a6, and 
MultiFinder 1.0b6 to developers for testing as of August 27, 
1987. This includes developer documentation on Juggler. The 
new system software is supposed to ship in September (which 
would be after you read this). And yes, we are interested in 
background task articles, but only for MultiFinder. Switcher is 
dead. To get these goodies, contact APDA about the Inside 
Juggler package. When released, it will be listed as System 
Software 5.0. -Ed] 

PRAM help 

Brett 

REMEMBER, if you don'thavea PRAM edit around and you 
want to get your Mac II operational again after the enevitable 
mystery ‘hang’, hold down the option, command and shift keys 
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while opening the control panel to clear the PRAM. (if it will not 
boot from the internal or SCSI, you can still boot from floppy to 
clear the PRAM.) 

Defense of MultiFinder & PRAM Bugs 

Jim Reekes 

Richard, the new MultiFinder is an extention to the Switcher 
rules. The Switcher-friendly resource (SIZE = -1) is compatible 
with MultiFinder. Anything that works under Switcher should 
work under MultiFinder, as with any other properly written 
software program developed to Inside Mac guidelines. If you 
don't have the documentation on Inside Juggler, then I don't 
think you should complain to Apple about your program bomb- 
ing under MultiFinder (and what version did you try?) Switcher 
was a total *hack* and I personally never trusted it on my system. 

Brett, the point that Tom Thompson was making about the 
PRAM bug in the Mac II was that *Е УЕМ AFTER THE OPT- 
CMD-SHIFT* procedure it didn't work. The “ZAP PRAM’ 
dialog doesn'talways work. Ihavezapped it numerous times and 
with no luck. I believe that there are some versions of the control 
panel with this bug. And I’ve had the bug mentioned in the 
MacTutor report for the last two issues. Yes, I hope it continues 
to get reported until it's fixed. 

Switcher/MultiFinder & Word 3.01 

Lsr 

I forwarded the comment about Switcher vs. MultiFinder to 
a Multifinder person, and he said that the problem has been fixed. 
The very first version of Multifinder used the same Switcher 
globals, so applications that explicitly checked for Switcher 
would get confused. 

Later versions don't use those globals, so this should not be 
a problem. Multifinder does not implement Switcher's back- 
ground task feature, since Multifinder's background processing 
capabilities are more powerful. (The Switcher bg task did not 
switch in the application, for example, because Andy Н. couldn't 
figure out how to make the switching fast enough.) The lastest 
Multifinder also implements the quickswitch features of 
Switcher 5.1, and works fine with Word 3.01. 

I hope this answers the question. 

Time to stir up the muck! 

Macowaco 

Yawnnn.. Gosh it has gotten quiet. Okay how about this. 
Anybody out there hacking away on HyperCard? Hey, I've 
gotten deep inside and I like the nifty Atkinson-like stuff I see, but 
(big but) why all the fuss! According to Scully, Hypercard is 
supposed to be to SW what the II was to HW. Sorry, but I don't 
think so. Hypercard is a more complex version of SlideShow (of 
course I'm being simplistic) and it's great for HABACRAP 
kinda stuff and for inexpensive laser disk access, but big press 
releases??? Hit of the show???? AWWW come on maybe there 
was alittle too much MAC enthusiasm in Boston. Maybe, this is 
actually all a snow job to pull the public's attention away from 
other more damaging things  like..... A-UX? 
NAAWWWWWWW! 

HyperHype 

SpUd PoTatO 
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Hear, hear for Macowaco’s last post; I remember Apple 
saying that FileVision would "revolutionize...". And what 
happened to Telos?!? 

I think that the term "stackware" is a lousy term to use for 
Hypercard “applications”. Let’s coin anew term for this; we here 
on the Mousehole represent a good portion of Apple’s developer 
base, so if we start using анаа нае "Warecards", 
or something else, it'll catch on.. 

Hyper Docs 

Richard Hyman 

I just called APDA, and the HyperCard Tech Ref Manual 
(#КМНТІ) and the MultiFinder Tech Ref Manual 
(#KMSMED) are available for ordering. These items appear to 
be very new - the individual at the order desk had a new memo 
as of yesterday, without prices, although she was pretty sure they 
are less than $25 each. HyperCard and Mutlifinder are not 
available; these are just the ref manuals. 

Regarding the hypercard hype, Sculley et al must be assuming 
that it will be important because most people buy Macs to process 
information. Word, Excel etc are the heavy sellers. A/UX will be 
important to just a small portion of the market. *Rick* 

Stackware 

Pete Harbeson 

I vote for cardware. Think of the possibilities...” Didja get the 
latest cardware?” “I dunno where the card is.” “Not card 
WHERE, cardware!” “You could try ServiceStar or Joe’s 
Plumbing Supply on Main street...” “No, no, not HARDware, 
CARDware!” “No thanks, I like checkers better.” 

Hyperware isn’t nearly as good; it just sounds like a line of 
sportswear put out by Jeff Goldblum. Or we could pay homage 
to the original WildCard title and call the stuff WildWare 
(hmmm...there’s a Van Halen song in there somewhere...)! 

Stack Overflow Revisited 

Fred Reed 

There are times when ID = 28 does not indicate stack 
overflow. 

I kept getting this error on a recent project, but prior to the 
error, there was plenty of room on the stack and I wasn't using any 
“piggish” calls. My investigation revealed the following : 

The stack sniffer routine which runs during interupt time (at 
about 60 times a second) compares the then current address of the 
stack with the address of the highest block in the application heap 
and reports ID = 28 if the latter is greater. The address of the 
highest block in the heap (which is not necessarily the same as 
ApplLimit) is stored in the first longword of the application heap 
zone header (i.e. the first 4 bytes of the application zone). 

Should the first 4 bytes of the application zone become 
corrupted with a value higher than the current stack address 
you'll get an ID = 28 error event though, in reality, the stack is 
fine. 

There are a number of ways that these four bytes could be 
overwritten, but in my case it was a system heap overflow. This 
occured as follows : 

To launch a document, I got the handle of the AppParm block 
in the system heap from the system global AppParmH. I SetHan- 
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dleSize of the document data and stuffed it. It turns out that the 
Finder always locks this block, sets the handle size, but does not 
unlock it (which I would call a bug). Thus, my SetHandleSize call 
failed. Of course, the real problem was that I neglected to check 
for an error after SetHandleSize. 

I suppose that there are more subtle ways of getting a system 
heap overflow, and it probably pays to check the first four bytes 
of the application zone if you get an ID = 28 error that is otherwise 
unexplained. 

Byte Benchmarks Rebuffed 

Jack Howarth 

We just got our Mac][ and MPW last week and decided to test 
those benchmarks. The results show Byte is guilty of sloppy 
journalism and biased reporting. The float benchmark on a Mac 
][ w/ MPW Pascal using the align words, 68020 and 68881 
compiler options gave a 10 sec benchmark. Our IBM AT with 9 
MHz 286 and 8 MHz 287 gave 35 sec. Now half the AT value to 
correct for the clock speed difference and you have the Mac ][ 
running 1.75 times faster which is not surprising. What about 
those benchmarks in Byte though? They show an IBM Model 80 
doing 0.48 sec for the float while a Compaq 386 does only 4.41 
sec. Although the Compaq is only running the 287 at 8 Mhz that 
correction will only bring the benchmark down to 2.2. What 
gives? Bogus benchmarks, thats what. If you look at the Motorola 
Apples vs Oranges booklet it notes that bogus benchmarks are 
often cited for floats where a calculation like: 

a:-b/c; а:= а*с; d:=a/b; d:=d*b; 

because they are using optimized compilers which drop out 
useless calculations like the above to d := a; Not a very fair 
comparision is it! By the way, the IBM AT float benchmark was 
done in Microsoft Pascal. TurboPascal gives a benchmark which 
is twice as slow for the AT. 

MultiMac 

Frank Henriquez 

Remember MultiMac? That was probably one of the most 
mysterious programs ever; it appeared without warning, actually 
did multitasking (not well, but the frequent crashes were no 
worse than those on an Amiga, with it’s “multi-tasking” operat- 
ing system/joke) and then, quite suddenly disappeared. No one 
seemed to know who the author was, nor what happened to it 
since it’s disappearance. Unlike MultiFinder, it ran on a 512K 
machine (with the old Roms, no less) and did multitasking. How 
come it’s taken Apple 18 months (or more) to come out with a 
program that does less? And what was the true story about 
MultiMac? 

On Bill Atkinson & Andy H. 

Deirdre L. Maloy 

Err... Don’t you mean “сапопіге”? “Cannonize” would be 
blowing someone apart.... 

Frank - I heard from a friend who talked with Andy Hertzfeld 
about MultiMac. Turns out Andy was quite impressed by what 
the European author (whose name I forget) managed to get a Mac 
to do, and this idea later worked out to be Servant/Juggler/ 
MultiFinder. In fact, MultiFinder LOOKS an awful lot like 
MultiMac, including the menu trick (but MultiMac had the menu 
on the right of the menu bar instead of on the Apple menu). 
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Copyright violation is the sincerest form of flattery... 

[Please note that Apple is very sensitive about the suggestion 
that Switcher or Servant in any way impacted MultiFinder. The 
official line is they did not; it was a seperate development 
entirely. Of course, once someone shows you how... -Ed] 

Fullwrite Worrles 

Pete Harbeson 

I just heard some disturbing (well, to me) news about 
Fullwrite. Although they were showing itat MacWorld and even 
posted "hours to shipping", supposedly that Microfilm-based 
electronic magazine (sorry, can't remember the name) claims 
that what was being shown was early beta, the program has big 
problems running under newer systems and finders, and proba- 
bly won't be available when they said it would be. That program 
looked like *exactly* what I need, and all this is BAD NEWS!! 
But...is it true? Anyone heard the same/different? [FullWrite is 
all it claims to be and more, and will ship *soon* and be great! 
Don't worry. -Ed] 

Hypercard visual effects 

Lsr 

The visual effect in Hypercard should work on a Mac II, but 
you have to be in 1 bit per pixel mode. Hypercard writes directly 
to the screen to perform the effects, but does check if the screen 
is not B&W before doing so. If the screen is not B&W then it 
doesn't use any effects at all. 

HyperCard 

Greg Kostello 

Just got HyperCard. Went to bed at 3:00 A.M. playing with 
it. Gad I hate new software. Say, does anyone know if it is 
possible to import data. I already have lots of information on 
other databases. I surely do not want to type the information in 
all over again. 

Also, the manual that came with the software is pretty 
worthless. Does anybody know where I can purchase a copy of 
the programmers manual? DoIhaveto go thru A.P.D.A? Thanks 
in advance. Greg 

Hypercard Import 

Lsr 

Look in the button ideas stack. There should be a button for 
importing text. Look at the button's script to see what it does; you 
should be able to customize it for any kind of input file. 

Hypercard 

. Luke Van Wontergh 

Just picked up Hypercard at the Home Computer Store - 17th 
& Tustin in Santa Ana. They have about 15 more copies. I was 
disappointed in the manual also. 

Byte Benchmarks 

The Atom 

Ап interesting note on Byte's latest 68020/80386 bench- 
marks (sept. 87 issue): 

If you take the top machines with best test results (DSI-780 
and Compaq 386 @ 16 mhz), when you calculate the average 
percent difference from each of the 6 tests and standardize each, 
you come out with the 68020 running 446 faster on average(for 
those 6 benchmarks). Of course that didn't stop Byte from saying 
the 386 was faster than a 68020. 
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Mac ІІ Command-shift-3 

David Holmgren 

Our Mac II now refuses to capture the current screen to disk. 
I had done this successfully twice before. Now it just beeps at me 
(on the first try after startup, it accesses the disk momentarily, 
then beeps). I tried running from floppy, replacing the system 
file, reseting PRAM; none produced results. There are no 
invisible Screen X files. It behaves as though there was insuffi- 
cient disk space for the screen dump. 

Mac Il Screen capture 

Maxbug 

If you want Command-shift-3 to work on your Mac II, set the 
Control Panel MONITOR: Black & White and to 2 colors. 

80MB disaster- 

What to do when your drive dies 

Jim Reekes 

First, run a bad block scan. If you get *any* bad blocks, you'll 
need to reformat the drive. I'm not too up on the Jasmine 
software, but it should include this utility. Next, try Disk First 
Aid's test, DiskExpress’ verify or Apple's SCSI Setup test 
option. I believe all of these perform a bad block scan. 

My first guess isthat you' ve got bad directory structures. This 
does not mean that you need to ‘Format’, but only ‘Initialize’ the 
drive. This can be done by simply selecting the disk in the Finder 
and choosing ‘Erase Disk’. MAKE SURE YOU ARE USING 
SYSTEM AND FINDER 4.1/5.5 or better. This is the only 
combination that properly supports a volume over 32MB. This 
is also why I'm guessing that it is the directories that are trashed, 
since you probably set up the drive originally with an older 
version of the System/Finder. 

There are a number of decent HD-floppy backup programs. 
Just about everyone I've seen will do the job, at least better than 
the Finder. Tape backup systems are still in their infancy. I figure 
in about a year we'll see the next generation. Look for major 
improvements once we start using DAT units for secondary 
storage. Personally I don't like partitioning software. There is 
no good reason (that I can think of) to partition multiple Mac 
volumes on a single drive. Remember that HFS means every 
folder *is* a partition. 

4d Alignment 

Max 

When designing the Input Layouts for data entry, 4th Dimen- 
sion jumps left-to-right, top-to-bottom on the form. If, for some 
reason, you want the next entry to occur on the right side of the 
form (rather than the default left), I found a shortcut using “Easy 
Access." 

First, align the tops of all the entry boxes on the region in 
question. Next, use the pointer to select the desired entry box. 
Engage Easy Access, hold down the “5” on the keypad, and tap 
once on the “8.” This will shift the box up one pixel; just enough 
to give that box precedence for data entry. You can barely see 
a one-pixel shift, but 4th Dimension knows it’s there. Problem 
solved. 

System 4.1 

Jim Reekes 

The system will determine the size of the volume and create 
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allocation blocks accordingly. On a 80MB size volume the 
allocation blocks are 1.5k. On my 140MB they are 2.5k. This 
means that a single char in a file will *at least* occupy 2.5k on 
the disk. 

68881 

Frank Henriquez 

The 68881 is the fastest of the currently available math co- 
processors. The 80287 isa bit slower, and sometimes even slower 
than the old 8087. I’ve heard of IBM slaves that plan on adding 
a 68881 to their machines (it would work, with some glue chips 
and LOTS of software). The 68882 is an improved version of the 
‘881, both in speed and accuracy. Intel is coming out with a 80387 
(andeven an 80487! - dream on!) and if it’s up to their usually low 
standards, it’s only going to be a minor improvement over the 
‘287. About Byte: The problem with the Byte benchmarks is not 
just that they were terribly bias, but that they show an astounding 
lack of professionalism for what is often considered the premier 
microcomputer magazine. If they had such a hard time getting 
reliable benchmarks, software and hardware for their Mac tests, 
and if they were truly honest and unbiased, they would not have 
published the three articles. Now David Betz has come up with 
Mac II benchmarks that do make sense. I wonder if they'll print 
a retraction or just print some sleezy explanation approved by 
their IBM masters... 

MultiFinder 

The Cloud 

Red Ryder doesn’t want to do anything in the background! 
Tonight’s quickscan was put on hold when I clicked in another 
window, and only resumed when I again made it the active 
application. Any suggestions? or do I look for another telecom 
program? 

The Complete Hypercard Handbook 

Keith H. 

Just picked up my copy of Danny Goodmans book. B.Dalton 
Book Sellers has a few copies ( South Coast Plaza & Westminster 
Mall in Orange County). One thing for sure is that it’s BIG, 720 
pgs., and the price may be a little high for some $29.95. But it is 
going to be the book to have for HyperCard as it gives a complete 
and in depth look at the program and how to program with it, 
some insight into how Bill A. came up with the idea for the 
program and more. Well I'm going back to reading my copy now. 

MPW 2.0 Pascal held up 

Rick Boarman 

Apple stopped shipping MPW 2.0 Pascal due to a very 
serious bug having to do with byte size array elements. Or 
something like that anyways. I don’t know if that effected the 
release of 2.0 Shell or not. I’m dying to use a new version of the 
Shell, the one I have now (2.0 B1) is very buggy. 

INIT’s 

Power Hopeful 

I'm having lots of trouble installing an INIT. If anyone can 
answer any of these GENERAL questions about the problem, it'd 
help. 

First, there is no REZ definition of an INIT resource. I'm 
simply linking my program as a DRVR then converting it to an 
INIT. This action assumes that the code will simply execute as 
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is, starting at the beginning. I have seen statements to the effect 
that an INIT must BRA somewhere, with that BRA instruction 
followed by 2 NOP's. In disassembling some INIT's — both in 
and out of the System file — I've seen that done. I've also seen 
that not done. Is this INIT definition applicable only to those of 
the olden days that had to be installed in the System itself? 

Second, whenever I doa_Blockmove to an allocated ptr in the 
System heap, the code which IS put there during the INIT (traced 
through) is not there later. I wonder if the info I'm setting in 
ResEdit (system heap and locked) is somehow not being saved 
and is thus making my code purgeable. Is there a bug in ResEdit 
that might be causing this to happen? If this were happening, 
would an INIT that was placed in either heap during early startup 
be removed after startup was complete? I mean, are purgeable 
resources purged during startup? 

Chlef Wizard 

The only rule governing the structure of an INIT is this: It 
must be executable code with the entry pointat the beginning and 
it must terminate with an RTS. 

You do not need to have a BRA with two NOPs. There is a 
standard developing, though, where people are starting their 
INITs with BRA instructions, and then following that with 
ASCII information about the INIT. 

When the System boots, it opens your INIT file with Open- 
ResFile, then it executes all of the INIT resources in that file. 
When it's done, it does a CloseResFile. ANY INIT RE- 
SOURCES STILL OPEN FROM THAT FILE WILL GET 
RELEASED! This means that any code you have in the INIT will 
be marked as free on the heap. 

To avoid this, you can do a couple of things. First, you can 
copy yourself to another non-relocatable block in the System 
Heap. Since this block is not a resource, it won't get released 
when the resource file closes. OR, you can call DetachResource 
on yourself. This has the effect of releasing yourself asaresource, 
but leaving the heap block around. 

Any INIT code that wants to live beyond boot time should 
load into the System Heap and should be locked. The Application 
heap at that time will not last very long. 

INIT's 

Power Hopeful 

Will a detached resource be invisible also to Macsbug? 

Lsr 

If you detach a resource, then Macsbug won't recognize it as 
a resource. If you copy the INIT code into a non-relocatable 
block, then Macsbug will report it in a heap dump, but you won't 
be able to tell (from that listing) which non-relocatable is your 
INIT. 

Microphone & Multifinder 

Alfred 

A while back I tried using Microphone with Multfinder/ 
Juggler and was deeply disappointed to find out that Microphone 
would not operate properly in the background (i.e. was not 
Juggler friendly). Every time I would switch to another applica- 
tion (Microsoft Word, for example), Microphone would turn 
itself off. Well, yesterday, I decided to see what would happen 
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if I cut out the SIZE ID=-1 resource from a Juggler friendly 
application and paste it into Microphone - It worked! I switched 
to the Finder and I could see text scrolling by in the Microphone 
window that was behind. I also tried doing XMODEM file 
transfers while fiddling around in the Finder and various appli- 
cations and they worked fine. Now I don't know about you, but 
Ihadalways wished I could do something else with my computer 
while I was in the middle of an hour long file transfer, and now 
I can! 

MultiFinder patch for apps 

Jim Reekes 

The patch you mentioned Alfred seems to work with most of 
the pre-MultiFinder applications. I suggest you COPY the 
resource out of MacWrite 4.6, and paste it into the program of 
your choice. If you read the article on the download board you'll 
see how this has been documented. 

4D Problem 

A layout procedure only executes when the record is being 
modified. To change the current selection while the record is 
being worked on is the equivalent of pulling the data out from 
under the pointer. If you HAD managed to do it (by calling a 
global procedure from within a layout procedure, for example), 
you would have gotten, probably, a bomb. 

The answer is to change the selection from a global procedure 
that calls the layout procedure. 

680X0 in a Mac Plus 

Michael Coren 

In view of the current craze in the Mac community for faster 
chips, has anybody tried putting a 68010 into a Mac Plus? The 
000 and 010 are pin compatible, and the microcode is a little more 
efficient to the point that a Motorola MPU guy told me that in 
normal operation at the same clock speed an 010 should be about 
30% faster than an 000. The only thing I’m concerned about is 
the 68010's “loop” instructions. Has anyone done anything with 
this? Also, would anybody know how to put a 68020 into a plus? 
Obvoiusly, itis possible since I know of 2companies that sell 020 
boards for the plus. 

Macowaco 

My old monstermac board had a 68010 in it. It was number 
49; areal early version back when Maxwell was making all sorts 
of performance improvement promises. He said it was clocked at 
the 68K speed and not 10mhz. This was a few years ago so the last 
time I cracked open the box (before I sold it) I looked to make 
sure. Yup, 68010. The Laserwriter has a 68010 in it too ya know. 

Anybody read Zachmanns’ column in Infoworld? Sigh, I 
have to agree with him regarding the level of fanatacism in the 
Mac world. Makes me wanna change my handle. Anybody see 


CMS SC40a 

Don Olson 

Bought a CMS SC40a from SnAPP and unfortunately found 
that the DOVE SCSI would not recognise it. After hassling with 
Dove and confering with Rusty, the Dove was the problem. 
Brought the drive up on a borrowed SE and was impressed with 
the speed. Does any one have any information on the caching 
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used in the SC40a? By the way, am returning the DOVE SCSI to 
be replaced with a Julian Systems SCSI at the recommendation 
of CMS. Thanks to Rusty for his leg work and a good deal on the 
drive. Keep up the good work. (Dove admits thier SCSIis at fault 
They want me to me to solder a lead from the SCSI interface to 
the RAM expansion board 512 to 1 M. Bozo huh?!) 

ADB Mouse Blues 

Gary Voth 

I have to agree with an OLD post of Jim's: 

I've notice a definite decrease in responsiveness when the 
ADB mouse is plugged into the keyboard rather than directly into 
the rear of the SE. It seems to get real jumpy, especially during 
floppy 1/O. 

Is it just me, or do any of the rest of you feel that the ADB has 
generally LOWERED the quality of the mouse feel compared to 
the Mac Plus? The Macintosh mouse is one of its better designed 
(and often overlooked) features. Every mouse I’ve ever seen on 
a PC has failed to implement the Mac mouse’s variable response 
ratio (pointer is 1:1 when the mouse is moved slowly, higher 
when the mouse is moved more quickly). Itis incredibly difficult 
to perform precise selections with one of these mutant PC mice. 

On the SE, NONE of the provided mouse settings seems to 
duplicate the slope of the response curve of the Mac Plus mouse. 
They either speed up too abruptly or not fast enough. I suppose 
I could get used to it, but it sure is disconcerting. 

Maybe the Chief Wiz could shed some light on the subject. 

SIMMs 

Keith H. 

Two places I have come accross that sell Imeg SIMMs at a 
good price are Computer Parteners, Beach Bl., Stanton, CA and 
Orion Avionics, Lawndale, CA (213) 676-0880. 

They both also sell other types of memory enhancements for 
all Macs I have dealt with Computer Parteners and can recomend 
them for all types of Mac equipment and software. 

ADB Sorrows 

Chief Wizard 

It appears that most of the problems with ADB are the result 
of the fact that ADB is a more complicated communications bus 
than the previous keyboard. Of course, previously the mouse was 
directly connected to a VIA which caused an interrupt whenever 
the mouse moved. 

Now, though, the mouse is treated as an ADB device which 
requires the more time consuming bi-directional ADB request 
mechanism. 

I don't have any concrete information about whether or not 
the mouse is actually slower when it goes through the keybaord, 
but I would tend to doubt it. In either case, the mouse is on the 
ADB bus, whether it is physically connected to the keyboard or 
not (i.e. if keyboard signals were colliding with the mouse, I think 
they would still collide when the mouse was plugged into the 
back of the Mac). 

ADB MOUSE 

The Atom 

It seems to me that the problems with the ADB mouse must 
be in the software drivers on the SE, since I run a ADB mouse 
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through a keyboard on a //GS daily, and the mouse and keyboard 
action are as smooth and fast as my тас+. 

inlines 

Palomar 

This is really great. In case nobody noticed, Apple also put 
some of this in the high-level interfaces in the final MPW 2 (and 
presumably IM Volume V), such as finding the System font size 
and number, and finding the menu bar height (128K ROM only). 
This goes a long way to making this code work with only a 
recompile if any of this ever changes in the future. 

However, MPW C only allows one 16-bit instruction; it sure 
would be nice if this simple restriction could be removed. (I 
know, nobody on this board cares about C.) 

Lightspeed & Switcher 

The Cloud 

The letter from Andrew Singer on p. 6 of the August MacTu- 
tor seems to say, if I read it correctly, that Switcher won't work 
under System 4.1...this is news to me, since I have been using 
Switcher successfully under 4.1 for a number of applications. Of 
course, Lightspeed Pascal isn't one of those applications. Curi- 
ous to see what would happen, I tried giving Lightspeed a 512K 
Switcher partition under 4.1, and got the message "The Light- 
speed Zone is damaged...proceed with caution”...so OK, it 
doesn't yet work with 4.1. However, most apps *do*, and it was 
a little disconcerting to read that they don't. I'm even more 
curious to know what it will do with MultiFinder.... Of course, 
MultiFinder will probably make Switcher a thing of the past, but 
until then, it's one heck of a useful utility (especially now that I 
have 2 megs! hee hee) -k 

Lightspeed and Multifinder 

Palomar 

One of the big Lightspeed fans on Usenet was saying that 
Lightspeed fails miserably under MultiFinder, and there are even 
some at Think who don’t believe this should be fixed. Rich 
(who’s also on Bix) spends all day using LSP and has worked 
closely with Think, so although I’ve not verified it myself, I 
believe it. 

It seems LSP does some funky stuff with the system environ- 
ment (like swapping in/out lo memory globals) and SUPRISE! 
MultiFinder does the same... 

MacApp @ MacWorld 

Lsr 

In case anyone is interested, there were about 6-7 MacApp 
programs being demoed at MacWorld. Briefly, they were: Joel 
West's picture colorizer (which also comes with some other neat 
things besides the MacApp program), a drum machine program 
called “Different Drummer”, a client management program 
called “GYST”, the Apple FaxModem application (which lets 
you send and receive faxes unattended, etc.), a backup program 
called “Мас Up”, a program called “Мар/Ассеѕѕ” which is а 
geographically-oriented data manager, an engineering applica- 
tion called "Mac COGO". 

Xpress 

Ram Warrlor 

Quark said they would be dropping the copy protection on 
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Xpress in the near future. Call them and complain - you may get 
a non-protected copy out of them. 

Due to bugs in their hard disk install program, we used FixJT 
to install (unprotect) our copy at work for hard drive use. It has 
worked well for 3 1/2-4 months now. 
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EventRecord question 

From: Frank Henriquez 

I've noticed a few programs that define the EventRecord as a 
constant. 

Message: DC.L Ø etc.. 

Since EventRecord is very much a variable, isn't defining it as 
aconstant, and therefore a code segment resident, a big mistake? 
(thereby asking for trouble with the 68020 and a real MMU). 


From: Jim Reekes 

Yes, defining the EventRecord (or any variable data) as a DC 
is a *serious* mistake. This code will break under future 
systems, and probably caching type processors like the 68020. 

I believe this problem was started way back in the original 
Apple MDS Programmer's Manual. In it, Apple printed example 
source code where the data records were defined as DCs. (proba- 
bly just alazy-mans way of avoiding the use of A5 offsets in their 
code :-) 


Assembly in general 

From: Frank Henriquez 

Maybe it's just me, but...assembly language on the Mac is fun, 
fast and EASY. 68000 assembly language is easy to learn and 
powerful, and using Mac specific routines is not much harder 
than inahighlevellanguage. I’ve noticed that I’m spending more 
timecoding than I would if I were using C or Pascal (so, what was 
a structure again? go get the C book. Oh yeah, that right. Now, 
how do I make this routine work? grab Inside Mac. OK, got 
it...hours later, I' ve forgotten what I was trying to do in the first 
place). IMis documented well enough that calling routines from 
assembly is no big deal. Iguess all this talk about how difficult 
and tedious assembly language is is just a rumor spread by 
assembly language programmers trying to keep their job secu- 
rity... 


From: Jim Reekes 

I AGREE with Frank. 68000 assembly on the Mac is very easy, 
considering other computer systems. The Mac has more calls to 
be used from the ROM than most other development systems. 
The 68000 has a wealth of instructions and addressing methods. 
Loading up the stack is very easy for passing parameters for trap 
calls. MPW Asm 15 the only way to fly. But, if you've got a large 
scale program in development you might get lost. (as I did) So 
I switched to Pascal for the bulk of the code, then re-wrote the 
procedures that needed speeding up. All of this is easy enough 
under MPW. [The two problems with assembly is losing your 
train of thought as the program gets bigger, and the difficulty in 
debugging. With LSP for example, I can find a bug immediately. 
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With assembly, I had to guess and go through several compile- 
link iterations. So I can generate much more code in the same 
time with Pascal. But there was a certain charm about doing it 
all in assembly... Oh well. -Ed] 


BYTE benchmarks: Mac vs. IBM 

From: Arnold Woodworth 

What really amazed me was the large discrepencies between 
the benchmark figures in the Mac ][ vs. IBM article and those in 
the Macintosh C compiler review (in the same issue of BYTE!!). 
Either something is wrong or a Mac Plus with a commercial C 
compiler is faster than a Mac ][. What did these guys use to run 
the benchmarks on the Mac ]? MS Basic? Don't laugh. If the 
Mac Plus benchmark times are divided by 4 (Mac ][ should be 
4 times faster in theory), they make the figures of the Mac vs. 
IBM article look like they were run with an interpreter. BYTE 
should get the Mac C compiler reviewer and the IBM vs. Mac ][ 
authors together and make them do an article on the differences 
between their benchmarks. THAT would give us meaningful 
way to judge which machine is faster. 


More MS bugs 

From: Peter Griffith 

Here's yet another bug in the MS 1.0 basic compiler: my data 
acquisition board sends the string +OVLOAD when the voltage 
exceeds the upper limit. Calling the function 
УАГ(“-ОУГОАР”) should return the number 0, but instead 
causes the stack to overflow onto the heap, resulting in a system 
error. Only thing to do is to check strings to make sure it's a 
number before using VAL. 


Apple Marketing Assistance 

From: Pete Harbeson 

How on EARTH does anyone get a straight answer out of 
Apple?? I called developer relations with a simple question (well 
.I thought it was simple) about any market research they might 
have access to focusing on the insurance/finance industry. They 
switched me to marketing research. THEY switched me to 
marketing. THEY switched me to some VERY strange office 
that seemed awfully paranoid that I was even talking to them 
(CUh...how did you get this number? You didn’t get it from 
Apple, didja?"). THEN I got sent back to the switchboard with 
instructions to ask for "business marketing". They weren't in 
(has anyone else noticed that Apple has entire departments that 
seem to take the day off together?!). GOOD GRIEF! I'd send a 
letter to somebody, but it'd probably just get sucked into some 
vast, endless, internal mailstrom at Apple and never get delivered 
(don't you think I' m doing well to keep my sense of humor?) (he 
stomps away, gritting his teeth and muttering “IBM software will 
be an easier sell in this industry anyway...grumble grumble...") 
[The Apple IIgs would suggest that Apple does not know what 
market research is and hence wouldn't know who should take 
your call. Does anyone know what identifiable market the IIgs is 
targeted for, given the pricing in comparison to a Mac? Apple 
representatives at the Paris Expo said 200,000 Apple IIgs sys- 
tems have been sold so far. -Ed] 


€ The Essential MacTutor, Vol. 3 


CRT filters 

From: Dirk 

Theeye strain is starting to get to me working on a CRT 8 hours 
a day, 5 days a week; not counting weekends. Does anyone have 
any advice or suggestions regarding the selection and purchase 
of a CRT screen filer (i.e. what's good, bad, etc.). Thanks in 
advance. [My eye doctor told me either give up computing and 
become aforestranger,or plan on buying glasses in increasingly 
stronger lenses. At least my metal frames look nice... -Ed] 


From: Jim Reekes 

Dirk, I personally bought and recommend a UV filter for the 
Mac. I believe mine was called "Perfect Vue”, or something close 
to that. The screen becomes a cool blue. I like it much better. 


Monitor tradeins 

From: Macowaco 

For those who might care; Apple developers will not be able to 
trade in their Monochrome monitors for RGB as the rest of the 
retail market can. It still costs less to simply purchase an RGB 
with the discount. [Apple Color monitors and 80 Meg hard disks 
are now shipping! I got both within the last few weeks. The tape 
units are supposed to ship "shortly" -Ed] 


Deals... 

From: Frank Henriquez 

MCM Electronics, a TV and electronics hardware supply 
company, is selling Macintosh flyback transformers for about 
$33.00... Then in EEN Times, there's an ad from Hamilton 
Electronics offering a 68020, 68881 and the PMMU for $400, all 
rated at 16 MHZ. If you can find someone willing to buy the 
68020 & 68881, the PMMU would “only” cost about $130. 


Lightspeed 

The Cloud 

I read with great interest Andrew Singer's comments in the 
August MacTutor regarding the “future” of Lightspeed on the 
IL..seems System 4.1 really knocked them for a loop (and 
everyone else).. *however* I am wondering about the code that 
Lightspeed ver. 1.0is presently generating...does it use any taboo 
addresses? In one of my LSP programs I call TrackControl for a 
scrollbar; my actionProc continuously redraws a drawing in the 
window to suit the value of the scrollbar. It works great under 
system 3.2 *but* «surprise!» causes an instant crash under 
system 4.1 the minute the scrollbar is clicked. Which gives me 
pause for thought, especially since I have now heard the rumor 
that code generated by LSP will not run on a Mac II. Well, I knew 
that Lightspeed itself wouldn't run (I don't have the beta 1.01 
version, but then I don't have a II either), but if programs 
developed with Lightspeed 1.0 are incompatible with the II (or 
System 4.1!) through no fault of the programmer then that is Real 
Bad News. Can anyone confirm this or shed some light on 
Lightspeed-created code? 


LSP 1.1 
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From: The Cloud 

After reading the Color Life article in this month's MacTutor, 
I noticed that it was written with LSP 1.1 for the II (obviously). 
apparently it (the 1.1 version) was released at the Boston expo. 
Are the new libraries/interface files included in this update? And 
will my programs compiled with 1.0 run on a MacII? or do I have 
to get 1.1 and recompile them? 

Oh, I wish I had an Ap-ple Mac-in-tosh Twoooo... That's the 
Mac I'd truly like to own... Cause if I had an Apple Mac-in-tosh 
Twooo.. ThenI'dprob'ly really hiss and moan. (until things start 
getting “fixed”) 

[LSP Ver. 1.1 isoutasa patch program. I have it and it works 
great, since I compiled the Color Life program with it. And there 
are new libraries for all the Mac II stuff. It should be uploaded 
to Genie and CIS by now. -Ed] 


A/UX 

From: Maxbug 

I just heard that Apple is NOT. going to ship A/UX on 40MB 
tape... They’re going to ship it on 80 MB drives! 

Hmmm...A/UX on an external 80 Meg Drive gives new 
meaning to the phrase UNIX BOX. 


LaserWriter driver weirdness 

From: Jim Reekes 

Question: What do you think will happen if I select to print 
pages 0 to 0 on the LaserWriter? 

Wrong toner-breath. Check it out. It doesn’t matter which 
application you use, it’s the LaserWriter drivers. Next I tried 
printing pages 0 to 9 using Word 3.01 and it continued to print the 
first page forever. I had to power off the printer. 


Hypercharger Revisited 

From: Dave Kosiur 

Just another note about HyperDrive/HyperCharger software 
upgrades. General Computer nows CHARGES for their system 
software upgrades! (I think it’s $30.00) They claim that it’s due 
to including a new Laser Spooler (they now use Think’s, not 
MacAmerica’s). 

For those of you who are interested, the latest version of their 
software is V3R2, which is meant to work with Finder 5.5/ 
System 4.1 (it does work), and includes special AppleTalk & 
Easy Access files for use with the HyperCharger. 


FKEYS,FULLWRITE,WORKS1.1 

From: Peter 

Just found out that my FKeys will not work (either Apple’s or 
the ones I installed) when I open a file in Microsoft Works (or 
Excel). Word is ok as аге all others I’ve tested so far. Is this 
generally known or what? Received my Visa bill today & found 
the charge for FullWrite that I ordered weeks ago. So I guess it's 
on the way (they promised not tocharge me until it shipped). Saw 
in Microsoft’s flyer that version 1.1 of Works is available. But 
no details. Does anyone know anything about this? [Microsoft is 
making a big deal about Works now being available on the IBM 
PC! Is this a trend or what? And yes, it is 1.1 now. I just got it. 
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There is no copy protection; you personalize your software 
instead. This is great! We commend Microsoft for this approach 
and encourage all software vendors to follow suit. VT 100 emu- 
lation has been added. Label printing has been improved includ- 
ing the Imagewriter jam problem! The Zoom box is now sup- 
ported so youcan't grow a window on a large screen and then not 
be able to shrink it on a smaller screen. -Ed] 


xlisp 1.7 

From: Maysong 

Does anyone out there know why xlisp 1.7 doesn't run on an 
SE? 


From: Roy Hashimoto 

Icouldn’t get xlisp to work on my Macintosh II, either, so I took 
the source code, fixed a few things to make it compatible with 
Lightspeed C, and rebuilt the whole thing. 

It seems to work fine on the Macintosh II and on a Macintosh 
Plus, so I have great confidence that it will work on an SE. The 
only drawback is that I haven’t yet figured out how to do the 
interface to the Mac Toolbox, so the toolbox, toolbox-16, and 
toolbox-32 functions are disabled. 


Bashing Macworld 

From: The Psuedohacker 

Since I seem to be in a ragging mood lately, I thought I'd 
mention that the current issue of MacWorld, the October Issue, 
has a very interesting editorial about computer journalists and 
their ethics or lack of them as the case may be. Throughout the 
editorial David Bunnell, Mr. PC World himself, mentioned 
certain examples and policies that his magazine never would be 
guilty of. For example if a product is poor, and users should stay 
away from it, Macworld will tell us, the readers. Also, their 
reviews, which “carry alot of weight", are always very thorough 
and objective, uh-huh. 

This comes from a magazine that's been known to not review 
products unless the publisher advertises in Macworld. They also 
just don't give negative reviews. 

Ican'thonestly remember the last time I read a negative review 
in Macworld but I do have fond memories of the multi-page 
spread on how to clean a mouse, that they published a couple of 
years ago. [Funny you should mention the mouse article. It was 
that article that inspired the creation of MacTutor! You might 
call it a case of "fluff overload" . -Ed] 
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What: System 4.2 

From: Jim Reekes (CMS) 

Okay, I spent about a hour getting my Mac II set up with 
System 4.2/Finder 6.0 and the same exact problem is still there. 
In PageMaker 2.0a, all Menus, Dialogs, and fonts within the 
document are totally garbaged. It is as if PageMaker cannot 
discover the proper font to be using, including the System font. 
So far this is the only application that I have had a problem with 
and I do blame it on PageMaker, not Apple’s system. But, as I 
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did mention before, this is a bug that I saw in the beta version of 
the System 4.2. 

The other major problem I had with upgrading to System 4.2 
was that the boot blocks have been changed. The first time I 
copied the new System/Finder to my system folder, the boot 
blocks did not get updated. This presented me with the shaking 
“Welcome to Macintosh” dialog at startup. So I check the 
original system disk’s boot blocks with FEdit and modified my 
hard disk to match. Now it boots up properly. [Looks like the best 
way to update is to use the Installer. We used it and had no 
problems. Also,I have not seen your Pagemaker problem, except 
on certain down-loaded fonts. As we reported last month, Page- 
maker 2.0 cannot place formatted MacWrite text correctly which 
uses certain down-loaded fonts, like the thin saratoga we use for 
all our source code listings! -Ed] 

What: MF Interactions 

From: Randy Saunders (Honeywell Inc.) 

I have two interesting MultiFinder interactions to report. I 
can work around them, but I would like to hear hypotheses on 
what causes them. 

1) Start up the new DA/Font Mover (3.6?) from the MultiFin- 
der. The first display (fonts in System) has all my fonts. Click 
the radio button for DAs, only 1 DA appears. Click the radio 
button for fonts and NO fonts appear. Clearly the message here 
is don't run the mover when the MF is using this data, but why 
the lost fonts? On second thought, why shouldn't the mover 
work? 

2) When running FreeTerm 2.0 under Finder 6.0 everything 
seems neat. When you run FreeTerm under the MF, and the host 
clears the screen, the program freezes up. Even the I-beam cursor 
flickers very dimly. Unless the host sends you a character, you 
seem to be stuck. І honestly don't have a guess what is going 
on here. [Lots of things crash under MultiFinder. The Lightspeed 
compilers bomb miserably. How about MPW? -Ed] 

What: ProApp and Wabash Computer 

From: Dirk (American Zettler, Inc.) 

I just found out yesterday that ProApp is owned and operated 
by Wabash Computer. Boy is it hard keeping up with the 
*players'. 

What: ICONs for INIT notification 

From: Jaff (Lake Forest, California) 

I'm writing a cdev that uses an INIT as well, and I' ve noticed 
that some of the newer ones (QuicKeys, ColorDesk) show an 
ICON when their INIT runs. Mine shows an ICON, too, and I'm 
wondering if there's a mechanism whereby I can offset the 
position of my ICON depending on what's been run before. In 
other words, can I tell who else's ICON is already on the screen 
so I don't overwrite it. 

What: ICONS for INIT31 notification 

From: Paul Mercer (SOL Systems) 

I wrote ShowINIT last Summer so I didn't have to resort to 
sicko windows for notification at INIT31 time (like TOPS). I 
have made the source code public domain hence its use in 
QuicKeys and other INITs. Leave me an address and perhaps I 
can get it to you. I'm on Delphi, AppleLink, and MCI Mail. How 
does one get on the MH dowload board anyways? [Register and 
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pay the dues on the Mousehole board. -Ed] 

What: Tape Backup 40 SC Blues 

From: Maxbug (Ashton-Tate) 

Apple's Tape Backup 40 SC ( ver 1.1) doesn't like FIND- 
SWELL! Volume Backup will ID=01 on a Mac II. If you have 
to splita backup across two tapes on an SE it never recognises the 
first tape again to write the catalog. The workaround is to move 
FINDSWELL out of your system folder and re-boot. After the 
backup you can put FINDSWELL into the system folder and all 
is well. (SYSTEM 4.1, FInder 5.5 ). [Try it again under the new 
systemandfinder.We have had no problems with the tape backup 
1.1 under the new OS ona Mac II. But be sure to have a formatted 
tape ready. It apparently forgets in the middle of a backup if it has 
to format a tape before continuing, making you start all over 
again. -Ed] 

What: Mac 11 Behavior 

From: Cpettus (Nova Development Corporation) 

I've been noticing some strange behavior in my Mac II, and 
I was wondering if anyone else has had the same problem or has 
an insight into it. Very occassionally (0.5-2 times per day) the 
Mac will freeze, emitting a high pitched whine. It seems to 
happen only during extensive disk access. The system will be 
frozen for 5-20 seconds, after which it will unfreeze and every- 
thing seems to be fine. While it doesn't seem to hurt anything, 
it is annoying and perplexing, to say the least ... Thanks in 
advance for any help or information. [This is a new one! Any- 
body? What we have seen is the color monitor display getting a 
case of the jiggles when first turned on. -Ed] 

What: ClipSaver 

From: Patrick Coffin (Ucla) 

Paul, ClipSaver is an init so that when a you quit a program 
or shutdown the mac the clipboard will be saved. I dont think it 
is Scrapsaver because it is only 543 bytes. It is a nice feature 
except that is does not work with MF using a Mac II. 

What: RR 10.0 

From: Patrick Coffin (Ucla) 

Ijustreceived RR10.0 today and just trying it out. Ithas some 
new features, but I believe that you still have to click after a file 
transfer which I feel is a real hassle if you are receiving multiple 
files from someone, and you want to leave your mac unattended 
for any reason. The person on the other end tries to send the next 
file and he gets no response, until you send a mouseclick. Why 
have autoreceive if you cannot receive multiple files? 

What: AppleShare Sharing 

From: Dave Goss (Mcdonnell Douglas) 

Sam Choi........ Yes itis true. Serial Baseband networks like 
AppleTalk can carry only one message at a time. If a second (or 
third, etc) us tries to send or receive something while that 
message is going down the pipe he/she must wait. The key to the 
thing's success .s that network activity is really pretty random, 
and itis more unusual than you may think for there to be conflicts 
(or contention, as the network designers call it). Just think of the 
cables connecting your stand-alone Mac to the disk drive and 
printer. How often are they ‘busy’ during anormal session. Most 
of the time you are pounding the keys, scratching your head, 
chatting with someone, etc. and those wires just sit there doing 


© The Essential MacTutor, Vol. 3 


nothing. If you were on a network, others could be using them 
and you would never know it. Furthermore, most data transfer 
sessions are fairly short, sq that even if someone does have to 
wait, it should not be for long. It generally comes down to how 
many users you have on the network and what kinds of activities 
they are engaged in. The folklore is that ten or twelve people can 
share an AppleTalk network without noticable degradation, but 
after that things can start slowing down if everyone is really busy. 
Again, the chances are that not everyone will be busy at once. I 
have seen up to 20 workstations coexist without serious prob- 
lems. Naturally things like games running on the net will have 
some affect, because they are using part of it’s capacity. The most 
realistic suggestion that I can make is to try it and see what 
happens. There are a lot of people using networks successfully, 
so don’t worry about it so much. Just go for it! 

I neglected to mention in the above, another very important 
factor that makes sharing a network practical, is packet data 
transfer. When a transaction, such as sending a file to the printer, 
is in progress that transaction does not hog the network exclu- 
sively. The network manager software breaks each message up 
into packets of data, which I think are about 600 bytes long. 
Between packets, other transactions have an opportunity to grab 
the bus and have one of their packets sent. The various transac- 
tions are thus interleaved so that nobody is left out in the cold. 
When things get busy the interval between packets of a given 
transaction get longer, but the data is still flowing. The guy trying 
to download a file off the server while the print file is being 
transfered may (or may not) notice that it takes a little longer, but 
he won't be left staring at a blank screen and wondering what is 
happening. 

What: RR 10.0 

From: Patrick Coffin (Ucla) 

Well RR has a lot of bugs, he is already coming out with a 
patch for some of them. The biggest problem is the pathnames, 
he only allows 39 chars. Which if you have a hard disk and RR 
is somewhat burried this becomes a problem. Other problems are 
with the proceedure commands; either he changed the command 
name or the syntax. And all the old proceedures have to be 
recompiled to be used with the new version. 

What: RR10.1 

From: The Dumacker (National Medical Homecare) 

Disregard the 10.1 upgrade completely. Patch for 10.2 is on 
the way. 

What: Capture to file by append (help) 

From: Mysteray (American Zettler) 

I'dliketo be able to capture files from BBS sessions. I can do 
it now (using Microphone w/ scripts), but always it is a new file. 
The Mac allows no spiffy way to copy multiple files to a single 
file (even CP/M could do THAT), as far as Iknow. Microphone 
will always open a new file on capture, even deleting the old one 
if it existed. 

Anyone know of a communications program that allows 
appending to an existing text file? This way I could put an entire 
months worth of MH (or other) into one file without having to 
manually append these using QUED or some other editor. Or 
another solution, other than to have ten or fifteen separate little 
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files that make finding things difficult. 

What: Capture File by Append 

From: Arnold Woodworth (Sterer Engineering And Mfg.) 

There is a way to make Red Ryder 9.4 (I don't have my 10.x 
update yet) append incoming text to an existing file. DON'T use 
"Capture Incoming Data to Text File" in the File menu. If you use 
the name of an existing file, it will be replaced, NOT appended 
to. Instead, you must write a procedure which uses the RECA 
command. RECA will open an existing text file and append 


incoming data to it. For example: 
RECA MouseHole:Messages 


will append incoming data to the file Messages on the disk 
MouseHole. 

What: RR 10.2 and MF 

From: Macowaco (Rockwell int.) 

I'mrunning under MF now and it seems to send the output to 
the window even when the window is under others. One has to set 
the SIZE resource in the same way as the one on the MHDL or 
one can just copy it in. I'll try a DL next. Too bad the Super- 
charged DL doesn't seem to work either. In fact the only DL I 
could do was with 1K blocks. 

What: On RR 10.2 & MF 

From: Macowaco (Rockwell Int.) 

Well, I tried DLing in the Background and while it seemed to 
work okay, the DL’ ed file was missing all it's finder attributes as 
well as some other data leaving it useless and with a blank icon. 
Too bad. Now I wonder if Hyperhype has the same size resource 
and if I can get it to chug away in the background. 

What: More MF - Problems 

From: Golden Ears (Seal Beach, Ca) 

Under MultiFinder, running SmartCom II v2.2B (regardless 
of whether or not it is the sole task) it will just assign the ol’ 
TEXT/MACA to all files downloaded ..... it isn't just Scott 
Watson. All the finder attributes were blown away. Hayes 
supposedly will be showing a MF version with all kinds of 
upgrades at COMDEX and will ship shortly after. ГІ believe it 
when I see it. I still like it better than anything else. If VersaTerm 
worked as it could, I'd use it (haven't seen this v3.1 tho....) 

What: Release MultiFinder 

The release of MultiFinder 1.0, System 6.0 and Finder 4.2 are 
on the MouseHole Download now. Somebody had uploaded the 
beta version yesterday claiming it was the release. It has been 
replaced with the real thing. Larry 

What: MultiFinder Funnies 

Just for yucks, do a COMMAND-OPTION select of “About 
MultiFinder" from the Apple Menu. True Holy Grail style. (it's 
also in STR#129 if you are poking around) 

What: Dynamac 

Look for a large "financial services" company to buy aLOT 
of Dynamacs in the next few months. Their salespeople will 
apparently be using them to do fascinating things like show how 
rich you'll be if you buy their insurance, etc etc. 

What: New Macll ROMs 

The new ROMs have ONLY the Slot Manager 24/32 bit 
addressing mode bug fix incorporated in them — that's it — to 
avoid drastic compatablility problems between ROM revs. [As 
reported in the press, the Mac II КОМ” slot manager cannot 
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properly handle a card with over 1 Meg of memory on the NuBus 
since it only runs in 24 bit mode. Certain NuBus memory cards 
over 1 meg, like National Semi require this bug fix. There may be 
other 24 bit bugs as Apple attempts to take the Mac II into full 32- 
bit mode. The memory manager is one that comes to mind. You 
apparently can get the bug fix ROMS by griping at your dealer. 
-Ed] 

What: Soundwave/SoundDesigner 

From: Tycho (Contel Business Systems) 

Well, I'm not an expert, but here goes... In response to a 
previous query about the differences between these two pack- 
ages, is a very rough generalization: Soundwave is a newer 
version of another product called "SoundCap", which is to be 
used with the old MacNifty 8 bit sound digitizer hardware for the 
Mac. This box will convert audio input from either a line or mic 
source into a digitized “sound sample". SoundCap allows you to 
edit and enhance (reverb, flanging, etc.) the sound, to be then 
played back on the * MAC *, resulting is relatively low quality 
sound. SoundWave adds a few new features, most notably the 
ability to “hook into” filtering and processing modules which 
YOU can write in C or Pascal. If you want more details, I have 
the package and can look them up. ONE 
WARNING...Soundwave has a BUG which crashes the Mac. 
According to Impulse, the publisher, this should be fixed “real 
soon now" (I think Apple Tech support is helping them but they 
seem to think it's not moving fast enough). Impulse says it 
happens only on some machines and not others, but MINE is one 
of the unlucky ones. SoundDesigner is a different animal alto- 
gether. It accepts digitized samples which are generated on 
professional quality audio “sampling keyboards" such as the 
Emulator II, Ensonique Mirage, Akai S900, etc. Sound Designer 
allows you to manipulate these samples in a much more sophis- 
ticated way, and then to download these back into the sampling 
keyboard, to һе reproduced using the high quality playback 
hardware that they offer. Most of the signal processing can also 
be done in the keyboards, but what they provide as a user 
interface is obviously less friendly than our favorite computer. 
The bottom line between these two packages is that Soundwave 
is a neat introduction to sound sampling and manipulation, and 
may be useful for specific applications, limited to its lack of 
interface to MIDI (and hence the inability to play the sounds back 
via keyboard, etc.) and the low sound quality of the Mac audio 
hardware. SoundDesigner is an expensive, pro-music “periph- 
eral" for the $1000+ sampling keyboards used by your favorite 
musical artists, and is worth every penny if you have such gear. 

What: favorite MIDI app 

From: Tycho (Xerox) 

I have been trying to use the latest version of Performer 
(Version 2.1) and it does offer lots of enhancements over previ- 
ous versions. Looping and looping within loops is supported, 
new dialog interface, lots of cutesie user interface tricks. 
However, I have two major complaints. It crashes, and it has an 
interface which is looking more like “M”/Jam Session/UpBeat 
with each release (and I’m repulsed by their idea of user friendly). 
I've given up and gone back to my Opcode Sequencer (2.5) after 
each attempt to work with Performer. It's easy to work with, 
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powerful enough, and gets the job done (without the frustration 
of locking up in the middle of a * HOT * recording session. 

What: Denver MUG 

From: Richard Hyman (Comp.Tech) 

For those in the Denver area, a new MUG is forming for the 
south metro area. The next meeting will be on Tues, 3 Nov. at 6 
PM. The location is the SAIC offices at 6021 S. Syracuse Way, 
Englewood, Suite 300. For more info, call Mike Phelps (SAIC) 
at 773-6900, or Blanche Cohen at 755-1525, or Rick Hyman at 
(w) 889-1200, (H) 973-8028. 

What: Dove Port 

From: Jim Reekes (CMS) 


Ihad talked with the VP of Marketing and a couple other tech 
support people at Dove. I informed them of the problems of 
using their port with a standard Seagate drive. They were baffled 
and could not provide a solution. They promised to send a SCSI 
port for me to test with. As of yet, Ihave never seen a Dove SCSI 
port. Icalled back a month later, and again they promised to send 
me one. This goes all the way back to the MacWorld show in 
Boston. At this time, I do not recommend the Dove port. 

Ihave been recommending the Julian System upgrade. So far 
nobody has reported to me any problems using it. I do not know, 
for sure, if it works. If anyone does indeed get the Julian port, 
please let me know how it works out. 

What: DataFlame.... 

From: Golden Ears (Seal Beach, Ca) 

While trying to assist a good friend who was duped into 
buying a DataFrame20 (not an XP) I discovered that things in the 
lands of SMS are not kosher. The bozo that answered the phone 
was obviously out of her depth even with fairly simple questions 
(although she did have an error sheet at hand, when Itold her that 
the Manager 3.03 app crashed to an id=02, she said hmmmm, 
let's see, that’s an address error....) furthermore she admitted that 
not only was that version of the manager a bad release but the 
subsequent 3.05 release was also known to be faulty, they 
SHIPPED BOTH of those versions to some poor unsuspecting 
customers. What galls me is that they could only offer to mail me 
a new disk which might arrive next week, no-one around there 
either had a modem or the brains to use it. After digging further 
into their documentation I discovered that they supposedly put 
their current apps on Compuserve/Genie/Delphi. I guess I will 
have to start up an account again. Why didn't THEY know about 
this ? But the real kicker is this, after digging up their Initializer 
v2.6 (which was known to be good) the bloody drive is faulty. 
This is the last straw with DataFrame and SMS, we had some- 
where in the vicinity of 18-24 of their drives at my last location 
and they were consistently a pain in the neck. (not as bad as 
HyperDrive, but then, is that possible?) Which of you have had 
a large number of units of a particular manufacturers SCSI hard 
drive in heavy use in house ? What are your experiences ? Whose 
would YOU recommend or purchase ? Why are so many manu- 
facturers quality assurance programs seemingly non-existent? 
As bad as their software was, and outrageously priced as it was, 
the AST-4000 was the most stable combo I have used (I don't 
think they even sell that model anymore) I had two of them 
running almost full time for over 18 months and no hiccups. 
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[I have had nothing but good results with DataFrame hard 
disks and with the company's response on service problems. I 
highly recommend the drive and the company. We currently have 
five drives in house. Admitedly this was before the merger. 
Things may have changed. -Ed] 

What: SuperMac 

From: Jack Howarth (Rice University) 

I believe the problem is that their tech support wizard left the 


company and no one there can fill his shoes. 
What: HD MTBF 
From: Macowaco 


Well, my experience with lots and lots of HDs has been that 
the Apple HDs have always been reliable and worthy of a major 
gamble. Although, and quite surprisingly the ZapSS 10s that were 
purchased (large quantities) have also shown to be fairly reliable 
too. If I had my choice of whatever I wanted regardless of price 
I'd go with the ProApp or CMS, both of which use the same HD 
HW. Lets face it, if you had to weight HD factors in making 
purchases- reliability is infinately more important then high 
performance. À note on Zap; while their SS10 has been pur- 
chased enmassat my workplace the only reason after their proven 
relibility is the low price. If one had a HD that had comparable 
reliability and under $500 then I'm sure my co. would look 
seriously at it. 

What: Dead SuperMac 19' 

From: Max (Microtimes Mag) 

Well, it really happened this morning... I was using the ol' 
Mac II system, equipped with a 19" SuperMac Spectrum (color) 
monitor. Turned my back on it for about two minutes, and when 
Icame back, the screen was black. Blank. Dead. Pulled out the 
fuse, and it was fried. Installed a new fuse, and it too, instantly 
fried. For the record, the monitor had been in daily use since last 
June, and has never had a problem. Anybody else have a 
SuperMac Spectrum go down? Or is it my Karma? Or what? 
What's a bummer is the dang thing weighs a whopping 85 
pounds, so you can'teven UPS ship itback to SuperMac! Ithink 
rush- fragile-freight for something this big and heavy will come 
to about $75... just to ship it in for repair! 

Since I have the unit for a magazine evaluation, we'll be able 
to find out exactly what went wrong, and I'll report back. In the 
meantime, many thanks to Mike Jewitt at Computer Partners in 
Stanton, CA. When the screen blew, I was оп a skin-tight 
magazine deadline, and he's provided me with a “loaner” mono 
screen. You can't beat service like that... which means mucho 
thanks to Mike, and Kudos to Computer Partners. 

What: MPW 2.0 Pascal 

From: Venus (Jet Propulsion Laboratory) 

My copy of MPW Pascal 2.0 finally arrived — sans any 
documentation, of course. grrr. Anyway, seems mostly every- 
thing is v1.0compatible. AndI still don't understand: whenever 
you compile a program, it creates a “%aSInit” CODE segment. 
What is this? ^ Apple's example, first thing, does an 
“UnLoadSeg(@_DatalInit);” to get rid of it. What's in this 
segment and is there anything useful you can do with it? Is it still 
an artifact from Lisa Pascal? Whatis the “_DatalInit” item? TML 
Pascal never had such stuff.. Luckily, I find most of my TML 
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code ports straight in, just change the compiler directives. 

From: Rich Siegel (Think Tech., Inc.) 

I think that the %aSinit is for initializing data; the compiler 
and linker both support initializing data, although the only usage 
if this I’ve seen is initalizing everything to $D2D7 for debugging 
purposes. 

From: Geoff Bryan (Latham & Watkins) 

What: Getting the screen size ina DA 

To get the screen size in a DA without using the AS register, 
declare a “rect” type variable and call this procedure: 
procedure GetScreen(var r : rect); 
const 

CurrentA5 = $0904;  (CurrentA5 lomem global)  ScrnBitsOffset = 116; 
{offset ScreenBits.Bounds} 
type 

IPointer = ^longint; 

IHandle = ^IPointer; 

RPointer = ^rect; 
var 

Ptr1 : RPointer; 

Handlet : Handle; 
begin 

Handle1 := IHandle(pointer(CurrentA5)); 

Ptr1 := pointer(ord(Handle1^^) - ScrnBitsOffset); 

г:= Ptri^; end; {screen rectangle) 

You can then examine the rect, r, for top, left, bottom, right 
values. Good luck. 

From: The Cloud (UCL A) 

What: Test for Multifinder Friendly 

Here's how I do it in Pascal: 

VAR 

MfPresent: Boolean; {global boolean variable) 
CONST 

WaitNextEventTrap = $60; {determine whether}  UnlmplementedTrap 
z $9F; (trap exists or not) 

BEGIN 

IF GetTrapAddress(WaitNextEventTrap) = 
THEN 

MfPresent:= FALSE 
ELSE 
MfPresent:= TRUE; {rest of init code here} 


Gipit) 


END; 


PROCEDURE MainEventLoop; 
VAR 
Event: EventRecord; 
Foo: Boolean; 
FUNCTION WaitNextEvent(mask: integer; VAR theEvent: Even- 
tRecord; sleep: longint; mouseRgn:RgnHandle): boolean; INLINE 
$A860; 
BEGIN (procedure) 
REPEAT 
IF MfPresent THEN 
Foo:= WaitNextEvent(EveryEvent, Event, 0, NIL) 
ELSE 
Foo:= GetNextEvent(EveryEvent, Event); 
IF Foo THEN {handle the event!} 
UNTIL HellFreezesOver; 
END; (MainEventLoop) 
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Thanks to Jim Reekes for documenting the above technique 
in his “Zippy” MPW source... 

What: Screen Size from a DA 

From: Lsr (Apple Computer, Inc.) 

To get the screen size from a DA, I might try looking at the 
port rect of the Window Manager port. You get this port with the 
trap GetWMgrPort. On a multi-screen system, this should be the 
size of the screen with the menu bar. If you are interested in the 
total screen area, look at the low memory global GrayRgn, which 
will be the total screen area, minus the menu bar. 

Also, am I correct in assuming that when a МасП is set (for 
example) to 8 bits/pixel mode, the ScreenBits global will be 8 
times normal size? I’m doing CopyBits calls from ScreenBits to 
an offscreen bitmap, and there is a dramatic slowdown in the 
program. Since screenBits is a BITMAP and not a PIXMAP, 
does it still contain all the depth info? Tech Note#120 (color 
pixmaps) demonstrates how to check the pixel depth of the 
screen, using the new routines....can I just calculate this info from 
ScreenBits instead? 

What: DrawPicture 

From: The Cloud (UC L A) 

I also have alot of pictures, accessed through picHandles and 
drawn in my window via DrawPicture. I'd like to be able to find 
a Q&D way of displaying them in color, preferably the “lazy” 
way, by calls to ForeColor and BackColor. Naturally, these only 
affect drawing done by the Quickdraw pen...or do they? Is there 
a way to do it without a major rewrite? Also, what happens if I 
set myPort^.bkColor to, say, blue, and then call InvertRect? will 
the result be black, or the color complement of blue? Thanks in 
advance for any experienced advice... 

What: Color Quickdraw Answers 

From: Chief Wizard (Apple Technical Support) 

First of all, the QuickDraw global screenBits doesn't have 
enough information to let you calculate the depth of a Mac II 
screen. For example, using a standard Apple monitor, 
screenBits.bounds would be (0,0,480,640) 
(top,left,bottom,right). Therefore, you would assume that a 
single row was 640 pixels across. This is correct. 

Now, to get the depth, you would probably divide 
screenBits.rowbytes by the width of the screen to see how many 
bytes/pixel were being used. To get the number of bits/pixel, you 
would multiply by 8. This won't work. 

In 8-bit mode, screenBits.bounds is still (0,0,480,640). And 
screenBits.rowBytes is $С000. The high bit is set to indicate that 
it’s a PixMap instead of a BitMap, so we remove the high bit and 
getarowBytes of $0400, or 1024. Using the formula above, you 
would get an answer of 12.8 bits/pixel. Oooops. What happened? 

The Mac II video card hardware is setup so that there is ‘extra’ 
memory to the right and below the actual screen ram. This 
memory MUST be included in rowBytes for the math to work, 
but it is not included in bounds because it isn't actually part of the 
displayed area. This was done to make the hardware simpler. 

Although all video cards may not do this, you can see why you 
can't use screenBits to calculate screen depth. (See TechNote 
#117 for more information about using the fields of a BitMap.) 

On Pictures: The pen color used when creating a picture is 
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actually stored within the picture. So if you call RGBForeColor 
(or just ForeColor) before drawing a picture, it won't have any 
effect; the pen color that was saved with the picture is used 
instead. 

There is, however, a fairly simple way to “colorize” pictures 
and bitmaps that were originally just Black and White. The 
operation actually only works on BitMaps, so if you want to 
"colorize" a picture, you would first draw it into an offscreen 
BitMap and then CopyBits it to your final destination. 

There will be a TechNote released in early November that 
explains this in detail. It'salittle long to go into here. But try this: 

DrawPicture into an offscreen BitMap. 

RGBForeColor(someColor); 

RGBBackColor(someColor); 

CopyBits from offscreen to your color window. 

What: Color with a K 

From: The Cloud (UCL A) 

Mr. Wizard: thanks for the detailed reply. Yes, I was indeed 
thinking exactly as you described...guess I'll have to GetMaxDe- 
vice, etc. to determine the screen depth after all. On the subject 
of “colorizing”, what effect do source transfer modes have on the 
color? Let me explain what I'm trying to do: I have a single 
picture (b&w) that serves two purposes: it's either drawn nor- 
mally (a “white” game piece) or inverted (a "black" game piece). 
Now, if I want to have “red” and “blue” pieces on acolor monitor, 
I would need to first draw the picture into an offscreen bitmap, set 
the on-screen window’s ForeColor to red, then CopyBits the 
picture onto the screen in “invert” mode (notSrcXor), so that the 
"white space" in the original picture becomes red. Am I on track 
still? Hopefully this is of general interest... As I don't have a 
MacII w/color here in front of me, I have to solve the problem “іп 
theory” first... 

What: Screen depth 

From: Lsr (Apple Computer, Inc.) 

To find the screen depth you have to examine the pixelSize 
field of the pixMap data structure. 

I think if you want to display red and blue pieces, you can set 
the RGB fore color to red or blue and use CopyBits to display the 
piece. CopyBits will make all the black bits in your offscreen 
bitmap be the same as the foreground color. 

What: Bitmap SLowdown 

From: Lsr (Apple Computer, Inc.) 

Copying from an offscreen bitmap (1 bit per pixel) to an 8-bit 
screen will be slow because Color Quickdraw will have to 
expand each of the offscreen bits to the appropriate byte (8-bits) 
corresponding to black or white. You will get the maximum 
copying speed when the source and destination are the same 
depth and have the same color tables. 

What: Red Game Pieces 

From: Chief Wizard (Apple Technical Staff) 

I've had a lot of success using CopyBits to copy a 1-bit 
BitMap to a multi-bit PixMap. This is especially nice when trying 
to add color. 

To color your pieces, you can do as you suggest except you 
don’t need to use the funky srcNotXor mode. Instead, you can 
just colorize the white part of the picture. In other words, do these 
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steps: 

DrawPicture into an. affscreen BitMap/PixMap. TechNote 
#120 shows how to create an offscreen PixMap. It's easy cause 
there is a call that creates the PixMap data structure for you. You 
just have to fill in a few fields. 

Next, when you want a red piece, Set RGBBackColor to red 
and CopyBits the piece. If you wanted a blue piece, you'd set 
RGBBackColor to blue and then CopyBits. 

It might be easier to use CopyMask, using an inverted version 
of the piece bitmap as the mask. That would let you CopyBits the 
piece without obliterating the entire CopyBits rectangle. (Does 
that make sense?) 

Also, if you are relying on Xor mode to draw and erase your 
pieces, I' m afraid that you will find the colors less than desire- 
able. Xoring and inverting colors usually results in less-than- 
appealing colors. 

What: The Red and the Black 

From: The Cloud (UC L A) 

Actually it does make sense. I won't need to do any “іпмегі- 
ing" of pictures when color is present. I' m still concerned about 
the performance issue Lsr mentioned, when copying from my 1- 
bit/pixel offscreen bitmap to the multi-bit/pixel screen. My 
current strategy is to allocate these bitmaps on the fly, and I 
discovered something interesting: if there isn't enough contigu- 
ous space in the heap for them, the Memory Manager has to do 
its thing, compacting the heap. This causes a “wait” of between 
1 and 3 seconds! The problem was solved by calling Compact- 
Mem at crucial points with a size slightly greater than the 
combined sizes of the bitmaps I was creating, so that there would 
always be a contiguous block free for them as they were needed. 
Naturally, multi-bit modes throw a curve at this approach; this is 
why I was concerned about finding the pixel depth.. An interest- 
ing sidenote to this discussion is the use of SuperPaint or 
GraphicWorks to create "color" pictures, which can then be 
pasted into a program (retaining fgColor info). But if you want to 
change the picture's color within your program (like I do) its 
value is limited at best... 

What: TML Pascal 2.5 

From: The Wombat (Edmonton, Alberta, Canada) 

Ijustreceived my TML Pascal 2.5 update (finally). There are 
no apparent changes to the compiler, it still bombs frequently on 
my Mac II whenever the monitor is in color mode. The compiler 
doesn't generate inline 68881 code, a special unit is linked to 
access the chip directly. Also the bug described in June/87 
MacTutor still hasn't been fixed. I'm rather disappointed. 

What: LightspeedC New Stuff 

From: Rich Siegel (Think Technologles, Inc.) 

Multifinder Niceties are on the way. We'll have a MultiFin- 
der-compatible version when MultiFinder is released. The 
source-level debugger will be coming later... 

Ihonestly don't know what the timeframe for The Big One is, 
though... 

What: ReadySetGo 4 

From: Dave Koslur (Connections) 

Just received my upgrade to RSG 4.0 yesterday. It's great! 
Style sheets, irregular graphics runaround, facing pages, the list 
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goes on.. I particularly like the ability to place graphics over 
facing pages for brochure design and the like. I'll keep you 
posted if I find any bugs. 

From: Keith Н. (Etak) #171 

I also got my 4.0 upgrade today. It is nice to have areal manual 
thatis nicely done, finally. The package also includes a little book 
called The Grid Book, which is a nice guide to page layout 
planning.I think they may have got it right this time as the 
program seems to perform better than ever. I will also watch for 
bugs but after the M.S. Word bug fiasco I went through anything 
else will seem minor! 

From: Mysteray (American Zettler) 

RSG4 is quite an improvement from the 3.0 version I suffered 
with (I got to h-a-t-e the "non"-scroll bars utterly). But it still has 
some shortcomings (or bugs, perhaps). 

The double-click selection of a word now selects the trailing 
space, which is fine for cuts and pastes (like in fixing word order), 
but quite lousy for doing underline attribute, which nobody can 
work out so it doesn't underline spaces if an entire sentence is 
highlighted. 

The 10%, 80% and 90% fill or pen patterns do not give a true 
gray fill. I noticed that the arbitrary run-around seems to repel 
more on the right side of text than on the left, perhaps because 
their algorithm includes the trailing space at the right end of a 


line, even though it is not selectable on screen. 

It is still slow on the first line below a graphic box with run- 
around on. I have had it do other strange things but not often 
enough to make conclusions to report. 

They fixed the reverse direction shift-click selection of a 
block (almost), which most Mac text processors fail (including 
QUED). For those who would like to try this on their favorite 
editor, here is the test: 

(1) set insertion point somewhere (several lines must be 
above) 

(2) shift-click the I-beam say three lines above the first one; 

(3) the text between these two points will highlight; 

(4) now... shift click anywhere within the block. What do you 
see? 

It should select the text from the lower mark (the first 
chronoligically). Repeating the shift-click should continue to 
select text from the lower mark backwards to wherever the 
click\was made. I only see this in MacWrite. RSG4 does it 
correctly except when the shift-click point is on the same line as 
the lower (original) mark point. Anyone else find an editor that 
does this correctly? (I don't have PM or Word to try here.) 
RSG4’s new tab settings are a Godsend. 
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Letters 


Vol. 3 No. 1 
Update Events - Who Does them? 
Clifford Story 
Murfressboro, TN 
I was very pleased to receive the first issue of my subscrip- 
tion today, within three weeks of sending you my check. Great 
service -something not common in the Mac world! 

Im sticking my neck out here but I believe Peter McInerney 
misunderstands the event manager's handling of update events. 
His letter in the November issue is a comment оп ап article, "Pop- 
Up Window Scroller" by Scott Boyd, in the September issue (I 
have not read the article). Mr. Boyd, in his program, called 
BeginUpdate and EndUpdate to "steal" update events. Mr. 
McInerney protests that these calls have no effect whatever on 
the event queue. I believe Mr. McInerney is correct but his 
observation is irrelevant. 

The point I want to make is that update events have nothing 
to do with the event queue either. They do not come from the 
event queue. Rather, GetNextEvent generates an update event if 
some window needs to be redrawn (and there are no pending 
events of higher priority). See Inside Macintosh, "Toolbox Event 
Manager", page I-245. 

How does the event manager determine that a window 
needs to be redrawn? It examines the update region; if it is 
nonempty, then the window needs to be redrawn, and an update 
event is generated. See "Window Manager" іп IM 1-278. 

One of the effects of BeginUpdate is to zero the window's 
update region. Thus, if Mr. Boyd calls BeginUpdate, he indeed 
"steals" an update event, since with an empty update region, no 
update event will be generated for the window. (Mr. Boyd must 
follow this call with one to EndUpdate to reset the visrgn, which 
is altered by BeginUpdate.) So there are wheels within wheels 
within the Macintosh, and all is not as it seems... 

Update on Update Events 
Stephen Hanna 
Cambridge, MA 

First, let me compliment you on the finest technical maga- 
zine around. Each issue provides at least one thought-provoking 
topic. Unfortunately, each issue also provides at least one misled 
technical comment. [If we knew it all, we wouldn't need MacTu- 
tor! -Ed] 

Mr. McInerney's letter in the November issue impels me to 
write and clear things up. Using the Operating System Event 
Manager routine FlushEvents to get rid of update events is 
useless since these events are never placed in the queue in the first 
place, but generated whenever GetNextEvent or EventA vail is 
called and there is no higher priority event pending. I look 
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forward to more letters from people living on the edge of what the 
Mac can do. Lets show those pinstripes with their PC's the 
meaning of "hot code". 
This Time The Author Speaks on 
Update Events! 
Scott Boyd 
Aggieland, TX 
Every time GetNextEvent occurs, the window manager 
checks the updateRgn of every visible window and if it finds a 
non-empty updateRgn, it posts an update event for that window. 
Thus, it is essential that updateRgn's are no different than before 
when I bring up the OverView window. My workaround to 
eliminate any update regions for the front window does this. 
Much of the feel of OverView is that it is fast and free of side 
effects, just like a menu. Thus, update events are unacceptable. 
If you can see footprints in the butter, we haven't done our job. 
Not worrying about update events is not the answer either, since 
what generates a non-empty update region for the front window 
is that I put another window in front of it: the OverView window! 
A good friend of mine, Greg Marriott, is writing an article on a 
much better way to implement fast pop-ups which eleminates the 
restriction that the pop-up not overlap windows other than the 
front window. OverView looks even better than before, and it has 
yet to cause the generation of a single update event. 
Help! MassTech Killed Me! 
Gary Mason 
4 Lori Lane 
Mendo, MA 01756 
I upgraded my Mac toa 512K, and then to 2MB with the late 
great MassTech Corp. of Groton, Mass. I have recently attempted 
the Мас+ Rom/Disk upgrade, and was greeted with abject 
failure. On power up, not even video appeared. I have since 
chased around trying to find someone, anyone, who can provide 
answers to these two questions: Can the MassTech 2MB system 
be upgraded to a Mac + status, and if yes, how?? I'm including my 
address in hopes some talented MacTutor reader will write me 
with an answer. Moral: Watch out for disappearing computer 
companies. 
Likes VIP 
Rod Paine 
Purcellville, VA 
А comment about your "Random System Crashes" you 
mentioned in the November issue. From what I've experienced, 
you are correct in suspecting the Cmd-Shift-3 fix for menu snap 
shots; it raised havoc with the fonts within my dialog boxes, after 
printing also. I've gone back to Camera DA. [I haven't had any 
trouble with the "official" Apple installer script fix...so far. -Ed] 
Also, on my two serial port MacBottoms and a new SCSI 


© The Essential MacTutor, Vol. 3 


MacBottom, I'm running System Files of 510K, but I've discov- 
ered that keeping the DA file at 13 DA's and the font file at 17 
fonts, my random system crashes are now a thing of the past. I'm 
not suggesting that these are "magic" numbers, but this info 
might help somebody identify whey these crashes are a fact, 
when more DA's and Fonts are brought into play, on either type 
of hard drive. [Yes, we've had several calls on this subject and 
while no particular failure mode is observed, the majority opin- 
ion seems to be that large system files, many DA's and Fonts, 
make the system file unreliable and crash prone. Apparently 
there are still "funnies" lurking in Apple's system software. 
Several have suggested however, that once you "construct" a 
stable system file, it tends to remain stable. -Ed] 

I also noted, that these random crashes, while within 
MacWrite, tended to occur more frequently when changing fonts 
or text size and saving a file. I was never able to get a sequence 
to repeat a crash, but it's happened enough times to cause me to 
gritmy teeth, asIdoa save. [MacWrite does crash when changing 
fonts in the entire document from time to time. -Ed] 

Lastly, great article on VIP by Bill Luckie! Гуе been 
working with the Mainstay folks for some time and they've got 
to be proud of this one! This may well be the application that lifts 
this heavy user out of his rut and finally gets me going down the 
road of programming. I've had a pre-release copy of VIP for some 
weeks now and it sure has started meon my way. With a translator 
for LightSpeed C coming, I think I just might be able to enter the 
Mac programming community some day and make some mean- 
ingful contributions. I look forward to the future columns on VIP 
and thanks again David, for all the effort that you've put into 
MacTutor, as it nears the beginning of it's third year! You've got 
a lot to be proud of too. [Thanks for the nice comments! -Ed] 

Calling Super Kelly to the Rescue! 
Jose Merhi 
Caracas, Venezuela 

After all I apologize for my bad english. I read with 
enthusiasm your column on Basic, which is the reason of this 
letter, to make a question for you. I see in a previous issue of 
MacTutor a program called window scroll bars in Basic using the 
CLR libraries. My problem is: I want to make a similar program 
but in ZBasic Compiler language, but I don't know how to make 
it. I write Zedcor and I implore to answer me this question, but I 
never receive any answer to my four letters! 

Another question: I have the last ZBasic manual and he 
explain how to save text in the clipboard, but the example on the 
manual only save 1 line of text. I wish to make change to this 
example to save more than one line but my results never is good. 
How до do this? [Your letter has been forwared to Dave Kelly, 
who will probably get a column on it in an upcoming issue for 
you. -Ed] 

Sue the Radio Station 
John Mancino 
Boulder, CO 

А rare but serious SCSI warning: This will only effecta few 
people, but if it does, it will drive you stark raving mad trying to 
figure it out. I was having problems at a beta site with totally 
random file corruption. I tried every possible combination / 
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replacement of software and hardware on the system to isolate 
the problem all to no avail. Finally, while making my umpteenth 
apology to the user over the phone, I happened to ask about the 
music that was always in the background on the phone but 
seemed particulary loud that day. It turns out that it wasn't a 
Musak Service at all, but a local AM radio station whose 
broadcasting tower was so close that anything electronic (they 
have electronic, not carbon receivers in their phones) picked up 
the transmissions. You gotit! Appleconfirms thatthe VLSI SCSI 
chips are extremely sensitive to AM transmissions because of 
their basic construction and the fact that the Mac case is relatively 
poorly shielded. The only fix that was suggested was a faraday 
cage surrounding the Mac and drive, or for either you or the radio 
station to move. 

Regarding system crashes, I had the same problem and 
could not resolve it until I replaced my downloaded 3.2 system 
from an official software supplement disk. Perhaps there are 
some bad 3.2 systems floating around. I'm using a Mac Plus with 
2meg MacMemory, LoDown drives and tapes. My system file is 
running 600-800K. I noticed that at seemingly random times 
after a system crash, the system file will be modified as much as 
500 bytes during reboot. I check the system file carefully after 
those rare times that I do have a crash and replace it if it has 
modified itself. 

Two final points. Has anyone noticed random disappear- 
ances of files while using SFGetFile dialog? Sometimes when I 
try to access a file in a folder on the SCSI drive, the file, which 
Iknow is there, does not appear. If Isimply copy that same folder 
to a floppy, the file is magically there when I call SFGetFile 
again. I am convinced there is a bug in the OS or packages 
somewhere. Also, has anyone had problems trying to throw away 
a folder that contains other folders and getting a message that in 
one of those inner folders is a file which is "locked or in use"? You 
then proceed to work your way to the offending file only to find 
out that it is neither locked nor in use. At this point you then throw 
it in the trash can (it may or may not let you do this) and go to 
empty the trash only to be told that it can't empty the trash! The 
final fix is to reboot the system, at which point you are allowed 
to trash the file. This happens more on SCSI drives, but I have not 
noticed it on floppys. [I have had this problem, but it appears to 
be legit. Checking such a file with ResEdit does show the busy 
bit set, which you can't reset without re-booting for some reason. 
Some programs create files and leave them damaged or open or 
something, that leaves that busy bit set. -Ed] 

TEScroll Bug - Tech Note 
Tom Saxton 
Salt Lake City, UT 

Your article "Extending TextEdit for Tabs" in the Novem- 
ber issue documented much of the inner workings of TextEdit 
and gave the courage to try it. In doing so, I found out that a bug 
I was having with the Chernicoff Text Editor's caret disappearing 
was from calling TEScroll with dh and dv both equal to zero, 
which apparently clears the low byte of the caretState field in the 
TERecord. This tells TEIdle not to flash the caret. This only 
happens with the new ROMS. I tracked this down with Macsbug 
and Lightspeed C, which makes symbols for Macsbug tracing. 
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Debugging INIT Resources With TMON 
by 
Paul F. Snively 
MacTutor Contributing Editor 


The past month or so has been pretty busy testing some 
things for some people and writing a desk accessory/INIT re- 
source combo. The desk accessory is called "Set Paths," and the 
INIT resource is ina file called "Boot Paths." Together they make 
a way to tell HFS to search up to five paths whenever it looks for 
an existing file. That way you don't have to worry about using 
pathnames in your programs. This is particularly nice for we 
TML Pascal programmers, who can say USES MemTypes, 
QuickDraw, OSIntf, etc. without worrying about pathnames! Set 
Paths/Boot Paths is shareware and should be on most major 
information services by the time you read this! 

However, what I really wanted to talk to you about, pro- 
grammer to programmer, is how I finally figured out how to 
debug INIT resources using TMON. 

You TMON users out there probably know what I'm talking 
about when I say that TMON showed a definite design deficiency 
in not being installable at boot time. Since TMON can only be 
used like any other application, its startup mechanism is simply 
the "Set Startup" function of the Finder, i.e. it gets launched 
AFTER any INIT resources (internal AND external) have al- 
ready executed. It's a drag, to say the least. 

Since I was dealing with an external INIT resource (one 
that's in its own file, rather than being installed into the System 
File) it occurred to me that I could try to reconstruct essentially 
what happens when external INIT's are executed. 

In case you don't know, in any System 3.0 or later there is 
an INIT with an ID of 31. INIT 31 has been documented in an 
Apple Tech Note, the gist of which is this: INIT 31 exists in order 
to allow programmers to modify the behavior of the system at a 
low level without directly modifying the System File. It does this 
by looking in the System Folder for any files of type INIT or 
RDEV. If it finds any files of that type it opens them and looks 
for INIT resources. If it finds any INIT resources, it executes 
them. Simple, huh? 

So the first step of my journey was to use MacNosy to 
disassemble INIT 31. I already had some idea as to how INIT 31 
had to work, and Nosy confirmed those suspicions. I was then 
able to conceptualize a VERY small piece of code that I could 
execute that would execute my INIT under debugger control! 

The question was: where do I put it? I'm really not that 
familiar with the Mac's memory map, and besides it'll be different 
from machine to machine. What] finally settled on was to use the 
largest free block in the application heap, and to put the code way 
up there in the middle of the block. This is an admittedly 
dangerous technique: itassumes that the INIT in question doesn't 
allocate much memory (most don't). 

So, with TMON in hand (or in 512e, I should say), I opened 
the heap window on the application heap. Scrolling to the end of 
the heap revealed that under the Finder I had a HUGE free block 
(the last block displayed). It started at 1Сххх or thereabouts, so 
I decided to put my patch at 20000. Here's what I came up with 
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(using TMON's interactive assembler): 


CLR.W -(AT) 

PEA FileName кы 
~OpenResF ile 

CLR.L -CAT) 

MOVE.L 8' INIT',-CATD 
MOVE. М 8 ID,-CAT) ;* 
-Ge tResource 

MOVEA.L CAT)+, AO 
MOVEM.L 00-Аб6,-(АТ) 
MOVEA.L CAB), AD 

JSR (AQ) 

MOVEM.L (A72*,D0-A6 
-CloseResF i le 

-Debugger 


Needless to say, a few comments about the code are in order. 
First of all, the asterisk comments mark instructions that you 
must supply values for. In the case of ID, the value should be 
whatever the ID of your INIT is. For a single external INIT, an 
ID of 0 works just fine. 

FileName, on the other hand, must be the address of the 
filename of your INIT file (a full pathname, too, for HFS' sake). 
Assuming that this patch is at 20000, I usually put the filename 
at 20100. To do this, open a TMON dump window and anchor 
it to 20100. Click on the second byte in the ASCII side of the 
window. Туре away! You can only enter one line at a time, so 
when you get to the end of the line, press RETURN and continue 
on the next line(s) as needed. When you are done (don't forget to 
press RETURN) count the number of characters in the pathname 
(count in hex). Click on the first byte of the first line in the HEX 
side of the window, enter the length byte, and press RETURN. 
Congratulations! You have just manually entered a Pascal 
STR255-style string! 

You can tell I'm an EUA user by the . Debugger at the end 
of my code. Standard TMON doesn't support the use of _Debug- 
ger (oops) so Darin Adler added that support in EUA. I just use 
it as a convenient way to get back into the debugger. 

Now, is the patch in place? Is the filename in place? If they 
are, there is one more important step you must take. Check the 
current value of the PC. Write it down. Now you can open the 
TMON registers window and set the PC to 20000. 

You are about to debug your INIT resource! Isn't that a 
GREAT feeling? Ok, now you can click on execute if you're 
feeling like a daredevil, or you can trace or single-step your way 
through it. Being a coward by nature, I chose to single-step. Boy, 
did I get an education! 

My patch worked fine. The CLR.W made room on the stack 
for the refNum returned by OpenResFile. _OpenResFile did its 
thing (but only because it wasn't in a resource other than CODE 
and DRVR. More on this later. Тһе CLR.L, MOVE.L, 
MOVE.W and _GetResource got my INIT for me. The registers 
were saved, the INIT's handle dereferenced (MOVEA.L 
(А0), А0) and finally - the moment of truth - the JSR (AO) passed 
control to my INIT. 
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So far, so good. I was staring my INIT code in the face in 
TMON! The labels to the left of the code all said: 
"ІМІТ0000--ххх," and the code was what I had written, all right! 

I continued single-stepping. I had just gotten to a PEA 
FileName, _OpenResFile pair of instructions (yes, Boot Paths 
has occasion to open a resource file). When I stepped the 
. OpenResFile, the system bombed with the ID = 2 (which, of 
course, TMON trapped). 

Here's a funny thing: the odd address was encountered in 
_RecoverHandle. What on earth was I doing in _Recover- 
Handle??? Back to Nosy... 

Rebooting the system, bringing up Nosy, and looking at 
_OpenResFile revealed something interesting: _OpenResFile 
checks the memory manager bits in the high-order byte of the 
address of the filename in order to see if the filename is from a 
resource (i.e. to see if the pointer to the filename is a master 
pointer from a dereferenced handle). Why? I still don't under- 
stand the purpose of this, even though I have since read the Tech 
Note that documents this OpenResFile bug. At any rate, I went 
back to my source and instead of saying: 

PEA FileName, —OpenResFile 

I said 

PEA FileName, CLR.B (SP), _OpenResFile. 

The CLR.B (SP) clears the memory manager bits of the top 
byte of the stack so that _OpenResFile no longer tries to _Re- 
coverHandle a nonexistent handle! That took care of my ID= 2 
bomb, and from that point on my INIT worked like a charm. Next 
time, I'll share some notes on what I call "not so standard file 
dialogs"! 

New Logo 
Andrew Shalit 
Somerville, MA 

Coral Software, in Cambridge, should soon be releasing 
Coral Object Logo. Coral's work has been mentioned in most of 
the places that Mac object-oriented programming has been 
discussed. Also, MacScheme+Toolsmith should soon be avail- 
able (finally!). Both of these will be complete development 
systems. Let me know if you'd be interested in articles in either 
of these languages. [Yes, we would! -Ed] 

MacTutor Does Foreigns Best! 
Dr. Christian Stratowa 
Vienna, Austria 

I am sending this letter to MacWorld, MacUser, MacTutor 
and Macazine because from the premier issue on of each journal 
Ihave all volumes and I hope this will be the case in the future too. 
I am subscribing to all four journals but it seems only MacTutor 
is able to handle subscriptions and renewals from a foreign 
country efficiently. Here is a summary of my results: 

MacWorld: I renewed on June 26 for a subscription due to 
lapse in August 86. By the end of October, I still had not received 
my September 86 issue although you can already buy the Oct 
issue in local bookstores. 

MacUser: Everything seems to work fine although some- 
times I have to wait rather long to get the different issues. The 
August 86 issue came with the September issue. 

MacTutor: I can congratulate MacTutor for the efficient 
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handling of my subscription. Until now I received ALL issues IN 
TIME, and the issue I received after my renewal contained 
already the mailing label with the new expiration date. Congratu- 
lations MacTutor, I am looking forward to the next issue. 

Macazine: I must say this is the worse case. I never got a 
renewal form. Although the expiration date was Aug 86, my last 
issue was the July issue. Besides the Aug 86 issue, I have also 
never received the Feb 86 issue. Because you cannot buy Macaz- 
ine in Austria, this means my collection is incomplete. I hope to 
receive a renewal and get my missing issues because I would not 
like to miss one issue of your journal. 

Likes Aztec C 
Nestor Murayama 
Lima, Peru 

Every month I wait for my MacTutor, the best informa- 
tion source in programming on the Mac, to find all those new 
things that make it so great. There's a very little world of 
programmers here in Perá, and we appreciate so much your 
efforts. What about more Aztec C help on ABC's of C 
column? I'm very excited about C as a language. Thanks. 

Will Apple Finish Appletalk? 
William May 
Clinton, MA 

Iam very interested in AppleTalk and have enjoyed reading 
(and re-reading) your series on the subject in MacTutor. How- 
ever, I have some questions that are not addressed in your articles 
or in the AppleTalk documentation. For the most part, these 
questions revolve around the business objectives of AppleTalk 
(vs the technical objectives). People in my company were re- 
cently looking at buying Mac Pluses for desktop publishing. We 
were disappointed to find that AppleTalk seems to serve mainly 
(only) as a method of sharing the LaserWriter printer. It does not 
seem to support file servers and other useful capabilities. There 
are third party alternatives, which raise questions of current and 
future compatibility problems. 

These then are my questions: where (conceptually did 
AppleTalk come from? From the user's point of view, what is it 
intended to achieve? Why not implement an existing standard, 
such as Ethernet? What are the design objectives behind some of 
the unconventional aspects of AppleTalk? Finally, where do you 
think Apple will go with AppleTalk; what can users expect to see 
developed? As Apple must know, there is a lot of potential for a 
fully functional AppleTalk. My question basically is why isn't it 
fully functional and when will it be? 

[You ask some good questions. Maybe some of the fifty or 
so Apple employees who read MacTutor will respond. Your 
letter is being passed to Bob Denny, our Editorial Board member 
who is our resident AppleTalk expert. Take a look at Tops and 
MacServe as server products. -Ed] 
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Seymour Cray on Macintosh 
S.C. Kim Hunter 
Mission Viejo, CA 
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In case you missed this gem from the Wall Street Journal, 
Dec. 30, 1986, I thought I'd pass this along to you. It seems John 
Scully mentioned at the December Boston conference on high 
technology how Apple had recently bought a Cray supercom- 
puter foracool$14.5 millionto design the next generation Apple. 
This prompted the following remarks from John Rollwagen, 
Cray's chief executive, as quoted in the Wall Street Journal 
article: "since they were good enough to buy one of our ma- 
chines, some of us have bought a few of theirs." Later Mr. 
Rollwagen told Seymour Cray, the company founder, about how 
Apple was using the machine, and he related Mr. Cray's reaction 
saying "There was a pause on the other end of the line, and 
Seymour said, ‘That’s interesting, because I'm designing the 
next Cray with an Apple!’ “ 

Prolog Wanted 
Greg Pisanich 
Redondo Beach, CA 

Hi! Being one of your loyal subscribers, I’ve noticed a real 
dearth of Prolog articles in your magazine. I mean, with two 
seperate advertisers spending all that money and no articles to 
help hype their product, you guys should be ashamed! [We are, 
especially since we have one article waiting to run! -Ed] Wait! 
No! No! Don’t tear the letter up yet! I’m not writing to criticize! 
I'm writing to ask for one of your author's kit. I’ ve been working 
with prolog on the Mac for awhile now and I'd like to take a stab 
at writing a series of articles your your excellent publication. I 
work at Hughes Radar, in El Segundo. Our department does 
software tools, although my work currently involves an expert 
system to be used in threat recognition (shoot ‘em down first!). 
Some of my school work at UCLA has been done in Prolog as 
that’s really the only chance I get to work with it. 

C Toolbox Tricks 
Jean-Michel Decombe 
Paris, France 

I have been reading you since the first issue. Since the first 
issue, I came to the conclusion that MacTutor is the best maga- 
zine for the Macintosh. It would be great if you could start a Trick 
Corner, where you would give the right code for the right need. 
For example, how to write a zoomrect() function, how to widen 
the prjobdialog in order to add buttons, and so forth. Here are 
some of my tricks in C and now I ask you: What is the best way 
to write in the data fork of the running program. I write this and 
it works, but I'm not sure it's the right way to do it. [Is there a right 
way on the Mac? (Note, this code has been hand typed.) -Ed] 

Writing to the Data Fork of a File in C: 


char thename (64); 

handle — thehandle; 

int thevolref, theappref; 
long thelong; 

ptr theptr; 


getvolC&thename , &thevolref ); 
getappparms(& thename, & theappref , &thehendle); 
thelong-BEFORE; 

fsopen( thename, thevolref , &theappref ); 
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fsread(theappref , &thelong, theptr); 
fsclose( theappref ); 


the long=AFTER; 
fsopenCthename, thevolref ,&theappref ); 
fswriteCtheappref , &thelong, theptr ); 
fscloseCtheappref ); 


ZoomRect() Function in C: 


zoomrect(srect,drect,expand) rect *srect,*drect; boolean 
expand; 

( 

grafptr saveport,deskport; 

rect r[17]; 

long unit; 

int count; 


ge tpor t(&saveport); 
ge twmgrport(&deskpor t); 
initportCdeskport); 
penmode(notpatxor); 
penpat(&gray?; 
for Ccount=8; count <=22;count++) ( 
if Ccount<=16) ( 
r(count]=*srect; 
uni t=Cexpand?count+ 1:33-count )*count/2; 


r{count].a. topt=Cunit*(drect-»a. top-srect-»a. top ))/ 136; 

r{count).a. lef t+=Cunit*(drect->a. lef t-srect->a. left))/136; 

r{count].a.bottomt+=Cunit*(drect->a.bottom-srect- 
»a.bottom))/ 136; 

r{count].a.right+=Cunit*(drect-»a.right-srect-»a.right))/ 
136; 


framerect(&r [count ]);) 
if Ccount? 26) 
fremerect(&r [count-6];) 
penmode(patcopy); 
penpat(&b lack); 
setport(saveport); 


The values employed here are the results of several tests. 
Before, there were formulas instead, but I tried, choosed the 
better values and put them instead of the formulas, for a greater 
speed. You must use the function with three parameters: the 
source and destination rectangles, in global coordinates, and the 
expand boolean (fast to slow or slow to fast zoom effect). Like 
this: 


zoomw indow( thew indow, openit) 

windowptr thewindow; 

boolean openit; 

( 

int theint; 

rect startrect,windowrect; 
se tpor t( thew indow ); 
setrect(&startrect,0,0,256, 171); 
windowrectsthewindow-?portrect; 
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localtoglobal(&windowrect.b.topleft); 
localtoglobal (&windowrect.b.botright); 
ifCopenit) ( 
zoomrect(&startrect, &windowrect, TRUE); 
showwindow(thewindow); ) 
else ( 
hidew indow( thew indow 2; 
zoomrect(&windowrect, &startrect, FALSE); ) 


Likes MPW 
Mark Lankton 
Boulder, CO 
While I'm sitting here I'll pass on a few thoughts about 
MPW... I’ve been working with the shell/assembler and the C 
compiler for about a month, and I’ve got to say I'm impressed. 
The shell is extremely powerful, and while it seems un-Mac-like, 
the convenience of using it to develop programs won me over in 
a hurry. I routinely rebuild a program (after a crash-debug-edit 
interval) with a single tap of the enter key... that's tought to beat. 
The C compiler makes tight, fast code, better than any other I've 
seen on the mac. There are already a nice bunch of tools around, 
and you can bet taht there will be many more in short order. It's 
good stuff, and if it isn't as flashy as Lightspeed at first glance, 
well look again. One thing for sure, it has the look of a system 
intended for use on some “serious” hardware- so bring on the 
new machines! 
StringOf Bug In LSP 
Evan Torrle 
Auckland, New Zealand 
I was trying to convert one of my MacPascal programs the 
other day into Lightspeed Pascal, when I came across the follow- 
ing bug. My Lightspeed version 1.0 will do the first bit okay using 
NumToString, but whenIgetto the second bit using StringOf, the 
variable j goes haywire and goes into an endless loop after the 
program has been run three times successively. [StringOf is 
buggy in the current version. -Editor] By the way, I think 
Lightspeed is the best software development system I've seen for 
the Mac. What would have taken me hours of frustration to bedug 
in TML, takes meonly 10 minutes in Lightspeed. The only things 
I wish for are a compile to assembly langauge option and 68020 
support. [We want those too! And an assembler! -Ed] Here's the 
bug: 
program LSBug; 
var 
i,j: integer; 
theStr ing:Str255; 
begin 
showText; 
(NumToString works OK) 
for i:=1 to 2 do 
for j:=1 to 2 do 
begin 
NumToString(i, theStr ing); 
WritelnCi,j2; 
end; 
( But StringOf makes the program go haywire! ) 
for i:=1 to 2 do 
for j:=1 to 2 do 
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begin 
theString:=Str ingOf Ci); 
Wr itelnCi, j); 
end; 
end. 
Comments on IC! Bug in NEON 
Paul Snively 
MacTutor Contributing Editor 


I just read the August issue with a great deal of interest and 
some amusement. As usual, I devoured Jórg Langowski's 
always excellent Threaded Programming column because he and 
Ihave acommon interest in threaded languages. To my surprise, 
he resurrected the old NEON bug in IC! along with a comment 
from BIX. There still seems to be some question as to why the 
IC! code insists on rebooting upon being executed. 

The ADDQ #3,SP instruction is indeed the culprit, although 
not for the reasons suggested in the BIX post. The problem does 
revolve around the fact that the 68000 is a word addressed 
processor. The author of IC!, obviously assuming that a byte- 
length instruction on a 68000 actually moves one byte, added 
three to the SP and moved the resulting byte. This code shows a 
flawed understanding of byte accesses using the 68000: a byte 
access alwaysinvolves two bytes, not one, so the code was wrong 
from the beginning. To move a byte from the stack might be done 
with ADDQ #2,SP followed by MOVE.B (SP)+,D0. Another 
problem is that the author of the IC! routine assumed that the SP 
could be manipulated like any other address register, which is not 
the case. Obviously, the stack register is crucial to the proper 
operation of the entire system. 

In elementary school we learn that adding an odd number to 
anevenone results in an odd number 10096 of the time. Since that 
is the case, adding three to the contents of the SP results in an odd 
SP. One thing that the stack pointer absolutely MUST NOT be 
made to do is contain an odd address! Since the 68000 is word 
addressed, all address registers - the SP included - must contain 
even addresses in order to avoid trouble. An odd address in an 
address register other than A7 may or may not cause problems - 

it depends upon the code. In the case of the SP, however, the 
situation is more critical because of the SP's importance to the 
system. 

The 68000 notices the bizarre state of affairs, says "That's 
odd!" and throws up its hands in despair. It knows of no way to 
react to an odd SP address but to react as if it had encountered 
what in 68000 parlance is known as a double bus-fault. That's 
about the worst thing that can happen to a 68000. Its reaction is 
to completely reset itself. Hence the spontaneous rebooting of 
the Mac upon encountering an ADDQ #3,SP instruction: it acts 
as a subtle version of RESET or JMP 40000A. 

This interesting observation leads meto conclude something 
disturbing about NEON. The IC! code of NEON is based upon 
a faulty understanding of byte addressing on the 68000 micropro- 
cessor, and is coded badly, to boot. To make matters worse, the 
problem has been discussed in print over a period of several 
months and no patch has been forthcoming from Kriya to fix it - 

and this over a period of time that has seen at least one revision 
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to NEON itself. Sufficeitto say thatI am somewhat unimpressed 
with the level of expertise shown by Kriya in their implementa- 
tion of NEON. It seems to have been written by programmers 
who were experienced FORTH programmers but who had very 
litle Macintosh (or any other 68000-based machine, for that 
matter) experience. (No offense to Charles Duff, Norm Iverson, 
et. al. - and Mr. Duff has since left Kriya and has most recently 
written a new object-oriented language for the IBM PC family 
running under Microsoft Windows called “Actor.” Perhaps he 
found the Windows environment a more friendly one in which to 
implement his vision of object-oriented programming, although 
this is pure conjecture on my part). 

By the way, it’s interesting to note that some clever program- 
mers (such as those at ICOM Simulations, Inc.) have used the odd 
SP trick to force a system reboot if their copy protection schemes 
fail to verify that the disk is an original. This is clever, because 
any instruction that forces the SP to an odd number will work, 
making the code difficult to find - what do you search for??? 
MOVEA.L #1,SP will work, as will SUBQ #7,SP or ADDQ 
#107,SP - it really doesn’t matter, as long as it’s odd. 

Amygdala Newsletter 
Rollo Silver 
PO Box 219 
San Cristobal, NM 87564-0219 

[Amygdala is a newsletter devoted to constructions based on 
the Mandelbrot set, a type of fractal. A picture of the Mandelbrot 
set is shown in figure 1. We think this is a very interesting area 
of research and would like to publish submissions on plotting 
Mandelbrot figures on the Macintosh. If you have such a pro- 
gram, please send for our author’s kit. -Ed] 


The Mandelbrot Set, M, is a subset of the complex plane (see 
figure 1). It has been called “Ше most complicated mathematical 
object ever discovered"; its boundary is certainly very convo- 
luted, and is in fact a fractal. It is named after Benoit B. 
Mandelbrot, the pioneer of fractals and the discoverer of M. It can 
be generated by a mind-boggingly simple process of successive 
squaring and adding of complex numbers. 

The basic question is: given a complex number z, is z in М 
or not? (note that a complex number z is defined as z = a+bi where 
a and b are reals, and i is the square root of -1.) We answer the 
question by generating a series of complex numbers z,, z,, Z}, ... 
from z as follows. 

Z= 2, 

Z,=Z, + 2, 
Z,= Z’ + Z, 
Z,=Z, + Z, etc. 

zis in M (z € М) if the moduli lz,J, 12.1, ... are bounded; 
otherwise (if the moduli are unbounded) z is notin M (z € M). For 
instance, starting with z = i, we get: 

z =i, 

Z, = -1+i, 

Z, = -l, 

Z, = -1+i, and we're in a loop; all 121< г, so z e M. On the 
other hand, starting with z=1, we get: 

20 = 1, 
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Figure 1 The Mandelbrot Set 


71-2, 

22 - 5, 

23 = 26, ... 

Iz| —eesole M. It’s not hard to show that if any Iz_|>2, then 
the series diverges to oo; so the test can be restated: z e Mif and 
only if all Iz | <2. 

So what? Well, it turns out that there’s a way of coloring the 
exterior of M, reflecting its mathematical structure, and the color 
“views” that you get by magnifying regions near the boundary 
are mind-blowing, and of inexhaustibly beautiful, literally infi- 
nite, variety. The book The Beauty of Fractals, by Peitgen and 
Richter, published last year, has many wondrous views of Mand 
other fractals, and much related math. The Computer Recrea- 
tions column in Scientific American (August 1985) was devoted 
to M, and probably launched the Mandelbrot craze. The coloring 
is related to the test mentioned above: for each z € M, there is a 
smallest n for which Iz 1>2, so each point in the complex plane 
Outside Mhas an integer associated with it, which I call its dwell 
number. Using any “coloring by numbers”, e.g. 0 = dark blue, 1 
= green, 2 = turquoise, etc., you color each point outside Mwith 
the color associated with its dwell number. 

A lot of people, myself included, are fascinated with Mand 
other fractals, and so I decided to put out a newsletter, 
Amygdala, for us. It’s available at the address above for $15 a 
year (10 issues) or $25 for Canada. You can get a sample issue 
free for a SASE. 
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Mac a Mystery 
David Price 
LA, CA. 

Iearn my living by designing and writing software packages, 
currently on an Alpha Micro 1092, which is a 68000 machine. I 
just got a Macintosh Plus for home. It seems to be an incredible 
machine, yet it has the un-nerving ability to make me feel like I 
don't know the first thing about programming! The amount of 
"front end" material to learn before one can make the machine do 
the most simple things is at times staggering. I came across your 
periodical in a computer book store, bought a copy and started a 
subscription the same day. It seems to be a magazine full of 
intelligent and useful information, although at times, I feel like I 
came in on the middle of a conversation. 

Youare doing a very good job, and I expect to learn alot from 
your experienced contributors. Please send a copy of The Best of 
MacTutor, Vol. 1 so I can catch up оп my education. 

A Heated defense of MPW 
Roger Voss 
Sector Research 
Huntsville, AL, 

The editor's aside comment in a letter appearing in the 
November 86 issue of MacTutor nearly sent me realing onto the 
floor! I quote “... we agree with this sentiment and are not even 
sure MPW is really necessary... “, end quote. I couldn't believe 
the absolute naivety that this comment represented, coming as an 
editorial comment from a programming journal for the Macin- 
tosh. [I stand by the statement, but your defense of MPW points 
out many of it'S worthwhile attributes, especially for large multi- 
person projects. -Ed] 

Everyone universally touts the latest programming environ- 
ments from Think Technologies as being the highest state of pro- 
gramming on the Mac. I agree that Lightspeed C and Pascal 
represent very worthwhile additions to the Macintosh program 
language repertoire. I strongly disagree that such environments 
are also "really" all that the Mac community needs in the way of 
software development tools and that Apple should "really" stay 
out of programming tools altogether. This attitude is highly 
unwarranted. [I never said that! -Ed] 

Compiler products from companies such as TML and Think 
Technologies are very good products and answer the need and re- 
quirements for a lot of folks that want to attempt programming 
the Mac. These types of products, however, ignore the require- 
ments, sophistications, preferences, efficiency-of-working-en- 
vironment, etc. of important numbers of Macintosh program- 
mers. I am speaking mainly of the non-amateur programmer; 
working professional software developers that earn their every 
tidbit of bread and crumb from writing applications and various 
system software for the Macintosh. 

Somehow or another, people have formed the notion that the 
epitome of a great development environment is very fast compi- 
lation and all functionality of the environment accessible via 
pull-down menus and other Mac metaphors. [It is certainly my 
preference. -Ed] When one is working on a large complex 
programming project that ranks into 25 or more seperate compi- 
lation units, composed of tens of thousands of lines of source 
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code, and written in a combination of Object Pascal, procedural 
Pascal, C and 68000 assembly language, one needs a lot more 
than only a fast compiler and a moderately adept make facility in 
order to facilitate the day-to-day grind of developing such a 
program. I can't begin to estimate the amount of development 
time and effort I have gained back on my side because of the 
MPW script language tools that I have written to deal with some 
Sticky aspect of my code development process. Over the many 
months that I have worked rigorously with MPW I have custom- 
ized the ease-of-use (and speed-of-use) of the shell/editor envi- 
ronment to very impressive simplicity. The versatility of the shell 
script language and MPW unix like tools allows one to create 
fantastic labor saving devices. I save time all the time that I work 
in the MPW environment because of the fact that it leverages me 
to work much more efficiently and effectively with a very 
complex project. 

I am very glad that Apple has so seriously pursued the 
development of a sophisticated and comprehensive software 
development environment for the Macintosh. The efforts of third 
party developers have not yet matched Apple's own as far as 
bringing forth truly powerful and professional development en- 
vironments for commercial software production. 

Well, I haven't dropped into the issues of combining multi- 
lingual compilation units; the options available for various levels 
of debugging information and debugging code generation; hav- 
ing various levels of code optimization; multi-levels of condi- 
tional compilation switches; environment variables that can 
inform compilers to use different source file interfaces and 
bodies under different modes of compile objective (and likewise 
with the linker for object files and libraries, and the make utility 
for make files). You know, the 68000/68020 assembler in MPW 
just by itself is more impressive than many third party compiler 
products. The code generation of the MPW compilers I would 
take any day over the Think Tech. compilers. The Greenhill C in 
MPW does a lot of subtle and not so subtle optimizations when 
you start looking at it under a debugger. I for one greatly applaud 
Apple for bringing MPW to the Mac world. [Look for an article 

on the MPW script language next month in MacTutor. -Ed] 
Human Touch Disappears 
Jeff Hopkins 
Canyon Country, CA 

Great Journal! The best yet for any computer system. I have 
a big question; what happend to Human Touch Computer Prod- 
ucts? I'm one of the lucky (unlucky?) few who received one of 
their Macintosh upgrade boards. It works falwlessly. The 12 Mhz 
68000 doubles the Mac's computing speed. This is one of the best 
engineered Mac products I've seen. Unfortunately, Human 
Touch no longer seems to exist. Has someone bought the line, or 
is it for sale? It’s a shame to see such a good product off the 
market. 

Mouse Freezing Effects 
John Baxter 
San Diego, CA 

In response to the item headed Folders and Mouse Freezing 
in the Mousehole column in December '86, I found that if I put 
Apple's Hard Disk Backup program into a folder on the HD- 
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20SC, that folder became a “‘deadly folder" as described in the 
column. I solved the problem by creating a floppy from which to 
run Hard Disk Backup (which makes sense, anyhow, since such 
a floppy would be needed for many restoration operations). The 
folder in question was in the root level directly. System 3.2, 
finder 5.3, stock Mac Plus. (How about more MacForth cover- 
age? It's my primary development system on the Mac.) 
Fortran Coverage? 
Paul Waterstroat 
Davis, CA 

Great magazine - keep up the good work! You are providing 
a unique and poweful tool to the Macintosh community. I've 
noticed that your Fortran coverage has been somewhat spotty of 
late. It is my opinion that the programming environment pro- 
vided to Mac programmers of Fortran is the weakest of any major 
language on the Mac. I feel the Fortran programmers have the 
most to gain from a tool like MacTutor. I hope that a regular 
Fortran column returns soon. [Fortran took a back seat waiting 
for Microsoft to finish fixing the package for HFS. Now that they 
have released version 2.2 (and sent us a copy!) weexpect to cover 
Fortran again as the CAD/CAM tool of choice for the new family 
of Mac workstations. -Ed] 

Fortran & QUED 1.5 Bug 
S.C. Kim Hunter 
Mission Viejo, CA 

Microsoft Fortran version 2.2 does not do integer to real 
conversions correctly. Try this example: 

PROGRAM DOSQRT 

REAL X 

X = SQRT(2) 

WRITE(*,*) X 

PAUSE 

END 

result: X = 5.3196E+08 

Now change to add decimal point to get the correct result: 

X = SQRT(2.) 

result: X = 1.414214, as expected. Moral: Don’t rely on 
implicit integer to real conversion in the Fortran functions. 

Here is areal bad one. QUED 1.5 just destroyed a MacServe 
volume on my XL hard disk! How? By printing more than one file 
to a Laserwriter from the finder when the QUED clipboard is 
active. Here are the steps that caused the problem (Believe me, 
don't try it yourself!): 

1. Install ОПЕР and 2 or more text files in a MacServe 
volume. 2. Setup QUED with ‘clipboard’ checked on the QUED 
edit menu. 3. Save QUED defaults (which makes clipboard 
active when QUED loads). 4. Quit to finder. 5. From a user Mac, 
access the MacServe volume with QUED and files. 6. Select 2 
or more QUED text fifels in the finder desktop. (Text files and 
QUEDareon the MacXL MacServe volume, being selected from 
another user Mac Plus or Mac 512) 7. Choose Print from the file 
menu. 8. Sit back and watch the fireworks. 

Qued does the following. It loads in with no menu bar (logo 
instead). The first file is printed OK, but not that the laserwriter 
dialog says *document: clipboard'! After that it's mush time. The 
post status of the MacServe volume is such that the MacServe DA 
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‘shared’, ‘private’ and ‘release’ buttons are dimmed on all Macs. 
Can't get at the volume! Any attempt to remove volume says 
volume is busy. The volume has to be deleted with Mactools. 

If the clipboard is deactivated in QUED, finder printing can 
work OK, but after the second file prints, the menu bar becomes 
active. Any attempt to do much of anything bombs with ID=10. 
QUED has a printer spooling feature, and is also able to print the 
clipboard. I suspect these options are confusing each other when 
using a laserwriter. 

Wants a good assembler 
Paul Meyerholtz 
Newark, CA 

I have been reading MacTutor for a couple of months and 
have found it a fantastic magazine. (I know you get a lot of these 
letters, but you always print them so you must not be tired of 
hearing it.) [I'm not! -Ed] 

I don't have a Mac of my own, but use one from work. I’m 
waiting for the 87 product announcements to get one for myself. 
Iam at the moment interested mostly in assembly and have MDS 
version 1.0. It is getting me started, but its deficiencies are 
obvious. When I get Mac, I'll also want to buy a new assembler. 
Do you have any comments on which is best? In the future I will 
also be programming in Pascal and hopefully C. I just sent off my 
membership to APDA. [I use the Consulair C as my assembler 
because it works better than MDS on a Mac Plus. But the best 
assembler by far appears to be the new MPW assembler. I' d take 
a good look at that one. -Ed] 

Likes VIP 
Jim Bishara 
Metairie, LA 

Ihavepurchased VIP andam very excited about it. Mainstay 
indicated that MacTutor will have some future articles on it. I 
have made some comments about VIP and sent them to Mainstay. 
Here are a few of them: 

-Printing from VIP wastes paper. Best to save as a text file 
and edit out unnecessary line feeds. 

-It feels “wrong” not to haveaRETURN statementat the end 
of a subroutine. 

-The cmd-D feature to interrput a program during execution 
is very nice. 

-VIP has a severe shortcoming in not being able to observe 
more than one variable at a time. This should be a high priority 
enhancement. 

-More explanation on resources should be added to the 
manual. 

-I don't understand how one could create a MacWrite type 
FONT menu in VIP since it doesn't support the following 
toolbox calls: GetFNum, GetFName and RealFont. These should 
be added. 

-А translator from VIP to Pascal or C will only be of value 
if it produces a complete program, not just the text equivalent of 
the VIP source code. 
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Those of you who have been around in the Computer fieldfor 
a while will recognize the name of Loy Spurlock, contemporary 
of Dan Paymar (Lower Case Adaptor for Apple II), Randy Hyde 
(Lisa Assembler) and Dave Gordon (Programma International 
& DataMost), fromthe early Apple II days. Loy started Computer 
Forum in Santa Fe Springs and presently owns a service com- 
pany inLa Mirada called Computer Quick which installs Levco' s 
MonsterMac. What makes Loy's company unique is that they 
actually scope out dead Macs to find out what killed them, rather 
than just do board swaps. From this perspective, Loy tells us the 
truth about the Mac power supply problem. -Ed. 


Macintosh Power Supply failures 
Loy Spurlock, President 
Computer Quick, inc. 

La Mirada, CA 


The Macintosh power supply has been getting a bad rap 
lately. I have seen articles written by “writers” claiming that the 
power supply is no good. The only reason those articles ever saw 
print was simply because they were written by a writer who 
normally writes for the magazine, not because they knew what 
they were talking about. 

The problem is, these authors don't know from Adam how 
the power supply works, what goes bad, or anything else about 
them —or they wouldn't have written the article. 

This whole hullaballoo reminds me of the same thing that 
happened with the Apple II switching power supply. The Apple 
II, much the same as the Mac is now, was a leader in the use of 
new technology. Up until the Apple II, computers were generally 
powered with the older transformer type power supplies. 

Anyway, at one point, there was a barrage of articles written 
about the problems with Apple's switching power supply —one 
such article was called, “A Worm in the Apple." All the “Au- 
thors" were bemoaning the fact that it was a switching power 
supply. If only it were frame transformer, everything would be all 
right. 

My guess is that when something is wrong, people are 
usually ready to throw the blame onto whatever is new. Since 
switchers were new to micros, that technology took the rap, 
rather than the amount of current it was designed for. 

In actuality, the power supply was designed to produce a 
certain amount of current at each of the various voltages. If Apple 
had used a standard transformer type power supply of the same 
currents, the problem these authors were writing about would 
still be there, but they would be writing about an under powered 
power supply instead of the weaknesses of a switcher. Also, if 
Apple had designed their switcher to produce more current, there 
wouldn't have been an imagined deficiency, and the Author 
would never have written the articles in the first place. More 
about designed current levels later. 

Why, then, did Apple not use a more powerful power supply 
to start with? At that time—and still today to a lesser degree— 
switching power supplies cost more than transformers. A trans- 
former with twice the power could be purchased for half the 
money of the switcher. Why, then, did Apple sacrifice power and 
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money just to have a switcher. Switchers have definite advan- 
tages, one being that they act like circuit breakers when some- 
thing goes wrong. For example, if you drop a pin on circuit board 
and short something out, the switcher will switch off, rather than 
continuing to produce current and fry the circuits on the board. 

Clearly, Apple was ahead of its time. Apple was right, the 
Authors were wrong. Today, switchers abound in high tech elec- 
tronics. You can get switching power supplies in a variety of 
voltages and currents. If the switcher had been so bad, they would 
not have grown to such prominence. 

Now, on to the Mac power supply. Is it weak? Was it 
designed poorly? In both cases, the answer is the same; maybe, 
but not for the reasons cited by the authors in the trade press. Let's 
take the scenario from the top and analyze why these authors 
think the way they do, and why they are wrong. 

Jim (fictitious) Johnson is hammering away at the keyboard 
one Sunday afternoon, trying to beat a Monday morning dead- 
line, and ..... smoke starts bellowing from the top left vents of 
his Mac. With a panic snap of the wrist, he reaches behind the 
smoking gun and flips the switch off. "Nuts," he mumbles, “ГІ 
have to drag out the old Radio Shack TRS80 to do this article". 

Monday morning; he turns in his ragged TRS80 printout and 
drags his Mac to the local Apple dealer. Right now, this very 
moment, given all these circumstances, this usually objective 
writer is in a very rotten mood. It won't take much to set off his 
short fuse. Then the word comes from the repair tech, “It was your 
power supply," he gleefully says with dollar signs in his eyes, 
"we replace more of these than any other thing in the Mac. It 
happens all the time." 

Now, you (you the reader of this article) are probably 
mumbling to yourself, I'll bet this really doesn't happen, Loy’s 
just made upa story to put his point across." I' ve got news for you 
buster. It happens all the time. 

Most local Apple dealer's have a service department to — 
what else?— provide service for Apple products. They have this 
service department for three reasons; 1) Apple likes them to have 
it, 2) It is a necessary evil to selling systems (when a prospective 
buyer asks where he will get his $10,000 system serviced, the 
sales person only has to point to the service window.), and 3) It 
does make a few (sometimes a lot of) extra bucks. 

In this service department, they usually have a service tech. 
However, because of the way Apple provides service support to 
them, they don'treally have to know very much. The Mac is made 
up of a motherboard (digital logic board- the part that does all the 
computing), the internal disk drive, the infamous power supply 
board, the video tube, and a variety of cables for connecting 
everything together. 

All the tech has to do to diagnose your Mac is swap the 
motherboard. If the computer works, it was the motherboard. If 
not, swap the power supply. If it then works, it was the power 
supply—and so on. 

When he finds that the power supply was the culprit, he 
gleefully tells you so and collects your money. 

After you're gone, he packages up your old power supply 
and ships it to Apple. Apple then has it repaired and ships it back 
to the computer store to be placed in yet another poor soul's Mac. 
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Ok, here's the rub. This so called “power supply” board is 
more than justa power supply. Itconsists of the power supply and 
the video circuitry. That's right, the video circuitry. The same 
kind of circuitry you see inside a video monitor that is used with 
the Apple II, and any other computer which uses a separate 
monitor. The problem is, when anything on this board goes out, 
the power supply automatically takes the rap because the board 
is generically called the “power supply”. Nothing is ever said 
about the video circuitry on that board. 

As president of an honest to goodness service, repair and 
upgrade shop (we have no system sales) which specializes in 
Macintosh, I can tell you that 9 out of 10 “power supply” failures 
is the video circuitry—not the power supply—part of the board 
(the rate is dropping as explained later). Furthermore, 8 out of 
those 9 video circuitry failures is flyback transformer failure 
(This rate is also dropping for the same reason). 

About 25% of the non-video circuitry failures is from cold 
solder joints—again, not a power supply defect. A cold solder 
joint is caused when not enough heat is used to solder a compo- 
nent onto the PC board. This usually happens in two specific 
types of instances; 1) When soldering a part into the PC board 
where the hole is part of a large foil plain, and 2) When soldering 
a part, which has extra large leads, onto the PC board. In both 
cases, more than the normal amount of heat is required in order 
to sufficiently heat up the larger amount of metal involved in the 
foil plain or large solder tail. Without sufficient heat, you get a 
cold solder joint. 

This leaves us with about 1 out of 20 power supply board 
failures actually being the power supply part of the board. 

Although I don’t have an exact scientific study to support 
these figures, they do come from an estimation after actually 
repairing several hundred Macintosh power supply boards. We 
repair them for retail customers as well as for other dealers all 
over the country. Most Apple dealer service techs simply swap 
power supply boards and send them to Apple for repair—he 
really never knows what the failure was. 

All early Macs had a small flyback transformer that would 
crack (probably due to heat). I’ ve cut failed flyback transformers 
open to see if I could determine what actually caused the failure. 
Itappears that a chain of events happened: the insulation material 
(grey in color) surrounding the windings was heated, the heat 
caused the insulation material to expand, the expansion caused 
pressure within the epoxy casing (red), the casing cracked due to 
the pressure, and separation of the casing caused the winding to 
short, open, arc due to loss of insulation, or a combination of 
these. In any case, it is evident that the insulation material was 
sufficiently hot to flow because the material is pushed out into the 
newly opened crack of the epoxy housing —evidently with 
tremendous heat because a bubble grows on the outer plastic 
cover (black). 

Next time your repair tech says, “Тһе power supply went 
out.", ask him if you can see your old one. Look at the big black 
part (about 1 1/4" in diameter and 1 3/4" tall) and see if it has a 
bubble on its side. It should be cylindrical in shape without 
bubbles. One note here though, the lack of a bubble doesn't mean 
that the flyback is good, only that having a bubble means that it 
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is definitely bad. 

If heat expansion is what causes these early flybacks to go 
bad, clearly a fan could help keep it cool, possibly preventing the 
failure. I know that Apple claims a fan is not needed. Obviously 
it is not, if you can accept failures that maybe would not have 
happened if a fan had been used. However, my feeling is that no 
preventable failure is acceptable if the prevention is less costly 
than the failure. Do yourself a favor, get a fan. If noise bothers 
you, get a MacBreeze Piezoelectric fan. 

Since our first day in business (October 1985), we have used 
a newly designed flyback transformer. In all the hundreds we 
have installed, not one has gone bad. 

Apple now uses flybacks from two new sources—one good, 
the other better. So far, we have replaced about 15 of the good 
ones, and only 1 or 2 of the better ones. It just so happens that the 
better one is exactly the same flyback we have been using all 
along. 

You might think that, considering we have replaced 15 of the 
good flybacks, it isn’t so good after all. But, also considering that 
in the same period of time, we replaced 50 or more of the older 
bad types. 

With the flyback problems dropping, the percentage rate of 
failure between the power supply and motherboard is coming 
into line where it should be. Before, we would have about 15 
power supply (with 12 of them being flyback transformer) 
failures to 1 motherboard failure. Now, itis about 10 to 1 and still 
dropping. As more and more of the older flybacks are taken out 
of operation, the power supply to motherboard failure rate 
continues to equalize. 

To heap on top of all the misunderstanding, we have scads 
of memory upgrades being added to Macs. We're not talking 
about only a few here and there, were talking about thousands 
upon thousands of memory upgrades. Fully 25% of all our 
customers have a 2 megabyte MonsterMac by Levco. Although 
this is probably higher than the average, I would guess that the 
entire Mac world probably has at least 1 out of 10 original 128K/ 
312K Macs with more than 512K. Remember the statement 
earlier in the article where I said, “when something is wrong, 
people are usually ready to throw the blame onto whatever is 
new." So, although the power supply (flyback transformer) 
would probably have gone bad without the upgrade, it is the 
upgrade that takes the blame for making the “power supply” fail. 

Percentage wise, our customers with MonsterMac upgrades 
have no more power supply failures than our customers with 
128K or 512K Macs. 

The Mac's power supply has plenty of power to support 
reasonable upgrading. As far as I know, there is only one part 
which has to be checked when doing a large upgrade. It seems 
that there was one batch of power supplies built with a weak diode 
at location CR17. This can be checked when adjusting the power 
supply. If you can get the 5 volt line up to 5.2 volts without 
crowbaring, the diode is okay. However, if it crowbars prema- 
turely, it needs to be changed (It doesn't need a different value 
part, only a higher quality part.) Since adding any upgrade to the 
Mac requires a proper power supply adjustment, doing this extra 
check is no inconvenience. 


© The Essential MacTutor, Vol. 3 


In adjusting the power supply, you can't simply set the 5 volt 
line at 5 volts and forget it. It must be balanced with the 12 volt 
line. If your upgrader does not understand “balancing the volt- 
ages", you should look for a different upgrader. 

This diode and proper power supply adjustmentare only two 
possible upgrading problems, I can think of, short of out and out 
over loading it. However, just because the MonsterMac can be 
easily powered with the Mac power supply doesn't mean that all 
upgrades can. Remember the first statement in this paragraph, 
*plenty of power to support reasonable upgrading." The power 
supply is not limitless. No matter how powerful Apple could have 
designed it, there would always have to be a limit. 

The point is, Apple had to give it a limit somewhere. If you 
design a car, you don't put a truck power train in it. It would 
simply raise the cost, and subsequently the suggested retail price, 
too high. So, when Apple designs a power supply for a computer, 
they design it to power what they have, what they feel they will 
add, plus a little extra for good measures. That was true for the 
Apple II, and is true for the Mac. If somebody wants to pull a 
trailer with their car, it is incumbent upon them to install the 
necessary power train and cooling system. If somebody wants to 
double the current requirements of the Mac, it is incumbent upon 
them to provide it. Apple cannot be held responsible for what 
others might to with their Mac. 

I, for one, feel that Apple provided ample extra current. It is 
well within reason. It will easily support two megabytes if 
properly designed. Remember, the Mac was originally designed 
to as an appliance, not to be opened and modified. Apple's only 
real goof-up was with the original weak flyback transformer, 
which they have corrected. My opinion is that had a fan been 
included in the Mac, they wouldn't have had nearly as many 
flyback problems. 

Sure, Apple could play it safe, and only use proven technol- 
ogy like IBM does—and always be 5 years behind the current 
technology. But I don't think any Mac or Apple II owner really 
wants that. We have our Macs because they are superior to the 
blue in ways blue owners simply can't understand. When I find 
mistakes that forward thinkers make, I always remember what 
my daddy told me more than 30 years ago. "The only people who 
never make mistakes are people who never do anything." 

If you still believe that the Mac power supply is bad, there are 
several implications: you believe what the writers wrote, you 
will do nothing different than before, you will probably have 
problems in the future—with the “power supply", motherboard, 
and everything else—, and you will continue to complain. 

If what I’ve written makes any sense to you, you will go out 
and have a fan installed (one that runs on 110VAC), you'll 
probably have less failures, and you'll be glad you own a Mac. 
Got a problem? Call us at (213) 941-7951 and we'll fix it. 

Information Overload 
George Deriso 
Apple Computer, Inc. 
Cupertino, CA 

After carefully sorting through and removing the clutter of 
my computer room at home, I've decided that information 
overload has contributed to its demise; I simply have too many 
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magazine subscriptions! I've chosen to reduce my number of 
subscriptions to two, and MacTutor is my first choice. 

How did I arrive at this decision? Quite simply, MacTutor 
is the very best and most significant Macintosh magazine to 
which I subscribe. It is the only magazine I read cover to cover, 
and I always get something valuable from it. 

I read issue number one, volume one and subscribed just 
after that (ah, the old MacTech days....). Unfortunately, I didn't 
subscribe in time to receive issue one, volume one, so that is the 
only one I'm lacking. [Number one is being sent to you, no 
charge. -Ed] 

Please keep up the good work. Yours is the only periodical 
that I find myself referring to time after time. “Enclosed, you will 
find another subscription order, as mine is nearly exhausted. 

Mac Programmers Wanted 
Karl Seiler 
Level Five Research 
Indialantic, FL 

Level Five Research is looking for Pascal programmers that 
have experience with the Macintosh. Level Five Research is an 
exciting, growth company in the AI field located on the east coast 
of central Florida. Wecurrently have the largest installed base of 
expert system development tools in the world. Our products are 
available on PC's, Digital VAX/VMS and we will be producing 
a Macintosh version next. Need immediate help. Please call 
(306) 729-9046. 

How the Mac Finds Things 
Dave Alverson 
Mason, OH 

In the ABC'sof C column in the August 86 issue, Bob states 
that Lightspeed C does not include the QD structure that is used 
to determine the screen size. This is quite true, but does not mean 
that Lightspeed has a problem. Lightspeed follows Inside Mac 
and defines the whole group of variables as globals. The screen 
rectangle can be referenced by screenBits.bounds. These globals 
are defined in the Mac Traps library, so this must be added to your 
project. You should also include QuickDraw.h, which declares 
the globals as external. 

In the January 87 Basic school column, Dave Kelly notes 
that the MS Basic interpreter is required in addition to the new 
Basic compiler to compile programs. Although the two together 
would make a nice development environment (write and debug 
with the interpreter then compile it for speed), I would be very 
surprised if the interpreter is required to develop a compiled 
Bascic program. [It's not. -Ed] 

Here are a few features of the 128k ROM or the Мас+ that 
have not been well publicized: 

Poor Man's Search Path: 

This appears to be the mechanism that causes the blessed 
folder and the “root” directory to be searched after the default 
folder. There is a function called via the HFSdispatch trap, called 
_SetPMSP, which can change this search path. Also 
FSPrivate.txt lists PMSPPtr at $386 that is a pointer to the list of 
directories on the PMSP. The SetPaths shareware utility, by Paul 
Snively, can be used to set the search path. 

Sector tags on 800k flopples: 
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While using FEdit on an 800k floppy, I noticed that the 4 
bytes of the sector tags that are defined as the time stamp of the 
write did notappear to be a typical time stamp. The highword was 
always zero. I think the 4 byte field has been redefined as the 
volume write count when the sector was written. 

Parameter RAM: 

Inside Mac Volume IV says that there is a new custom clock 
chip in the Mac Plus that adds more non-volatile RAM. The 
original clock chip has 20 bytes of Parameter RAM. The new 
clock chip has a total of 256 bytes of PRAM. The additional 
memory seems to be undefined so far, except for 4 bytes that hold 
a validity status flag for the new memory locations. The value for 
the bytes that says it's valid is ‘Bugs’. There are new traps called 
. ReadXPRam апа WriteXPRam. 

ROM Space: 

The Mac Plus motherboard ROM sockets have one more 
address line than the 512 motherboard, so 256K worth of ROM 
can be installed on the Plus. The 128k ROM startup code uses this 
fact to determine the hardware configuration of the Mac and sets 
the bits in HWCfgFlag (the word at $B22). Bit 14 is set to signal 
that the new clock chip is present and bit 15 is set to signal that 
the SCSI interface is present. (See Tech Note 37) 

Fortran Comments 
Roy Mendelssohn 
Santa Cruz, CA. 

The Feb. 1987 issue of MacTutor had a letter from Kim 
Hunter claiming that there was a bug in MS. FORTRAN 2.2 
because it "incorrectly" found the SQRT(2). To quote from the 
manual: 

"Intrinsic functions contained in the math library do not 
follow the typing rules for user defined functions and cannot be 
altered with an IMPLICIT statement. The types of these func- 
tions and their arguments list definitions appear in table 9-1" 

Why then doesn't the compiler return on error at compile 
time? The answer is simple. FORTRAN passes addresses, not 
values. Suppose I had set I2, and then said Y=SQRT (I) The 
compiler would pass the starting address of the 32 bits of I to the 
function. These 32 bits would now be assumed to be in real 
format, and would be so converted. I know of many Fortran 
programs that use the fact that FORTRAN passes starting 
address to pass integers to reals and vice versa assuming that 
there will be no conversion of the 32 bits where the variable is 
stored. This may bother people who program in other languages, 
but it is a feature of FORTRAN in many compilers. To had the 
square root of 2, therefore, conversion is necessary to a real 
variable. 

I feel it is worth-while to warn people that as stated in the 
manual FORTRAN intrinsic functions must have arguments of 
the correct type, but I would hardly consider this a bug. 

32K Segment Limit 
S.C. Kim Hunter 
Mission Viejo, CA 

I recently started using Lightspeed Pascal and was immedi- 
ately slappedon the hands for defining procedures and arrays that 
were too large. Digging into the manual, I find that Lightspeed 
Pascal has a fundamental limit of 32K for all procedures and for 
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any data structures defined within a procedure. This is attributed 
to the fact that “the Macintosh restricts the size of a code segment 
to 32K bytes" stated in the Lightspeed Pascal manual on page 5- 
4. Somewhere else in the manual I recall a statement that the 32K 
limit was supposedly fundamental to the MC68000. 

I was struck with the fact that nowhere in the MacFortran 
manual is any mention made of any limit of 32K, nor anything 
about segmentation. Why? Turns out that, according to Absoft, 
MacFortran was programmed without any use of the Macintosh 
segment loader. They didn't even bother to figure out how to use 
it. They just load the program and run it. So there is no constraint 
at all regarding the 32K limit imposed on the segment loader. 

So my question is: How come all the other programming 
environments are hung with this ridiculous limit? TML is. Turbo 
Pascal is. MPW is. Surely Absoft is not that much smarter than 
all the other folks. There must be some reason the others have to 
usethe segment loader. Hopefully someone can tell me more than 
“just because its there". Meanwhile, I’m trashing all my Pascal 
compilers and going back to Fortran. 

[The segment loader and the other compiler products use a 
16-bit offset to address the various procedures from a base 
address. While itis true the MC68000 only allows a 16-bit offset 
to a base register, obviously, this is not the only way to address 
the various subroutines in memory! Hence, Fortran, which was 
ported from another computer, can address subroutines any- 
where in the 16 megs of memory of the 68000 because they don't 
use this particular addressing mode to keep track of things. The 
other companies simply took the easy route and followed 
Apple's defective lead. Apple turned the linear addressing space 
of the 68000 into an Intel type partitioned memory! -Ed] 

Here are some benchmarks I've run using a simple 
SQRT(2.0) operation: 


SQRT(2.0) Benchmark 
Number of Square Roots per Second 

Apple II (VisiCalc) 0.55 
HP-41 Calculator 4.3 
Apple Пе (Spreadsheet) 4.7 
Apple Пе (Applesoft Basic) 21.5 
IBM-PC portable (1-2-3 ver. 1a) 49.0 
Mac 512 (Excel) 74.0 
Mac Plus (Excel) 91.0 
Mac XL (Lightspeed Pascal) 245.0 
Mac XL (MacFortran 00) 602.0 


Mac Plus, Novy 68020/81 (Fortran /20), cache 40,667 


This benchmark shows an 80,000: 1 ratio over the 10 years 
represented by the various microcomputers! 
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Postscript Plotting 

Philip Baumeister 

Loomis, CA 

As a new subscriber, let me convey thanks for a great 
magazine. But as many of your letters seem to contribute infor- 
mation, I seek it. When I write my own plot graphs, I approximate 
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curves the quick and dirty way, with short segments of straight 
lines. The line itself is drawn at 300 dots/inch on the LaserWriter, 
but (alas!) the locations of the ends of the line are in pixel 
coordinates, which means that there are steps, and a resolution of 
only the nearest 1/72 of an inch in the location of the line. What 
can I do? 

[This may or may not answer your question as you expected, 
but you might try writing two plot routines; one for the screen in 
quickdraw, and one for the LaserWriter in Postscript. The fol- 
lowing sample program does this. It displays a black box with a 
plotted line using quickdraw on the screen in Microsoft Basic 
(see fig. 1). Then it opens a text file and writes a short Postscript 
program to the file that when downloaded to a LaserWriter, prints 
the same thing but in Postscript. This way you can plot at the 
LaserWriter resolution of 300 dots per inch. -Ed] 

REM Basic Postscript Demo 

REM by D. Smith, MS Basic 

CLS 

WINDOW CLOSE 1 

MENU 

MENU 1,0,0,"File":FOR i3 TO 6:MENU i,0,0,":NEXT i 

MENU 3,0,1,"Demo" 

MENU 3,1,1,"Draw Line" 

MENU 3,2,1,"Quit" 

ON MENU GOSUB eventloop: MENU ON 

idle:GOTO idle 


eventloop: 

MenuStuff 2 MENU(O) 
menuitem=MENU(1) 

ON menuitem GOSUB Draw, Quit 
RETURN 


Draw: 

WINDOW 1,",(100,75)-(350,150),4 
WINDOW OUTPUT 1 

GOSUB screendraw 

GOSUB Postscript 

GOSUB screendraw ' update window 
MENU 

RETURN 


Quit: 

CLOSE 

WINDOW CLOSE 1 
MENU RESET 
END 


screendraw: 
TEXTFONT(0):TEXTSIZE(12):TEXTFACE(0) 
LOCATE 3,10:PRINT “Here is a Basic Line” 
LINE (10,10) - (60,60),33,bf 

LINE (15,15) - (55,55),30 

RETURN 
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Postscript: 

FIL1$=FILES$(0,"Enter Postscript File ...")F ҒІ1%-” 
THEN FIL1$="LINE.TXT” 

МАМ1%-ҒІ 1% 

OPEN NAM1$ FOR OUTPUT AS #1 

PRINT #1, “%!PS-Adobe-1.0” 

PRINT #1, “%%Title: Postscript Line” 

PRINT #1, “%%DocumentFonts: (atend)” 

PRINT #1, “%%Creator: Basic" 

PRINT #1, “%%CreationDate: 3/1/1987 5:30 PM" 

PRINT #1, “%%Pages: (atend)” 

PRINT #1, “%%BoundingBox: 0 0 612 792" 

PRINT #1, “%%EndComments” 

PRINT #1, “%%Document prolog now follows" 

PRINT #1, “grestoreall” 

PRINT #1, "initgraphics" 

PRINT #1, “/pageproc{} def” 

PRINT #1, “%%EndProlog” 

PRINT #1, “%%Line Example” 

PRINT #1, “%%Procedures now follow" 


PRINT #1, "/Times-Boldltalic findfont” 
PRINT #1, “36 scalefont setfont” 


PRINT #1, "/fillbox" 

PRINT #1, "(newpath" 
PRINT #1, “125 360 moveto" 
PRINT #1, “O 72 rlineto" 
PRINT #1, "72 O rlineto" 
PRINT #1, "0 -72 rlineto" 
PRINT #1, "closepath" 
PRINT #1, "0.0 setgray" 
PRINT #1, "fill" 

PRINT #1, "def" 


PRINT #1, "/box" 

PRINT #1, "(newpath" 
PRINT #1, “120 355 moveto" 
PRINT #1, “0 82 rlineto" 
PRINT #1, "400 0 rlineto" 
PRINT #1, "O -82 rlineto" 
PRINT #1, “closepath” 
PRINT #1, “0.0 setgray” 
PRINT #1, “stroke” 

PRINT #1, "def" 


é rile Edit Demo 


Here is а Basic Line 


Fig. 1 Plot a line In Quickdraw & Postscript! 
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PRINT #1, “Aine” 

PRINT #1, “{newpath” 
PRINT #1, “130 427 moveto” 
PRINT #1, “192 365 lineto” 
PRINT #1, “1.0 setgray” 
PRINT #1, “stroke” 

PRINT #1, "def" 


PRINT #1, "9596 main program" 

PRINT #1, ".8 setlinewidth" 

PRINT #1, "fillbox" 

PRINT #1, "line" 

PRINT #1, "210 380 moveto" 

PRINT #1, “.7 setgray" 

PRINT #1, "(Here is a Basic Line) show" 

PRINT #1, ".1 setlinewidth" 

PRINT #1, "box" 

PRINT #1, "showpage" 

PRINT #1, “%% End of Example" 

PRINT #1, “%%Trailer” 

PRINT #1, “%%Pages:1” 

CLOSE #1 

RETURN 

V.I.P. Improves! 
Tom Nalevanko 
Mainstay, Agoura Hills, CA 

Thank you for your coverage of Visual Interactive Program- 
ming; V.I.P. users and potential users appreciate the comparitive 
viewpoint that can only be provided by a multi-language interest 
publication like MacTutor. 

Since the release of V.I.P. in January, we've received a 
number of letters from customers expressing their satisfaction 
and offering suggestions for improvement. Since we couldn't 
answer all of these letters, we did an even better thing. We took 
the best suggestions and implemented them in a new version 2.1 
of V.I.P. This update will be sent, at no charge, to all registered 
У.ГР. users in March. 

The V.LP. v2.1 update includes the following improve- 
ments: 

Feature Extensions: Ability to access all fonts, ability to edit 
Case logic structure, use of window with “grow” box, ability to 
use “About...” in apple menu, movement about the flow diagram 
using arrow keys, use of any ASCII character in a string, etc. 

New Intrinsic Functions: err, point, toplft, botrgt, and rect. 

New Procedures: draw character, string to scrap, scrap to 
string, get pen position, set text mode, is real font, get font name, 
move, line, get picture info, get window title, get active window, 
undo text, get text, set dlog/alert font and set print options. 

Supplementary products that we have announced will be 
available in April. These include translators to MPW C and 
Pascal, Lightspeed C and Pascal, and TurboPascal as well as 
external procedure classes: Speech Manager, Grid Manager, 
Database Manager, Multi-user Database Manager and the Matrix 
Manager. [See the VIP article in this issue for a discussion of the 
LS C translator, which is now functional. -Ed] 

MS Basic Compiler Code Expansion 
I.N. Botnick 
Los Angeles, CA 
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I've been a BASIC programmer for seven years, from the 
Apple II+ to the IBM PC and finally to the Macintosh. I’ve used 
IBM Basic I & II, QuickBasic, BetterBasic, True Basic, ZBasic 
and now MS Basic on the Mac. I want you to know that the 
Microsoft Basic Compiler for the Macintosh is one of the worse 
compilers I have ever used. It is unbelievable that a company of 
Microsoft’s reputation would put out a compiler that is so bad. 
Take a look at the chart below: 


Program ASCII Size Compile Size Memory Use 


8] 148K 375K 625K 
92  12TK 327K 558K 
83 111К 293K 525K 
"4 93K 254K 475K 


Each of these programs was designed torun in 330K to 465K 
of memory, but as you can see, the compiler is generating 
unusually large code. One main reason is because they are putting 
8 bytes in front of each statement for error and event trapping. 
Program #1 has 8300 statements but only 2550 lines. In all my 
years of programming, I have never seen a compiler that pro- 
duced a 375K executable program from a 148K ASCII file! With 
this version, I still cannot: 

1. Run a program from a compiled BASIC program. 

2. Read the names of files on a disk and load them into an 
array. 

3. Get the amount of space available on a disk. 

4. Create a folder 

5. Delete a folder 

6. Find the name for a volume without using the FILE$ 
statement. 

7. Set a volume's name. 

8. Find the size of the current screen. (New Macs, remem- 
ber?) 

9. Use color (New Macs?) 

10. Init a disk. 

11. Get the name of the current printer. 

12. Get the name of the file that was clicked to launch the 
program. 

13. Open an included library without a fixed path name (a 
Macintosh No-No!) | 

Microsoft Responds 
Art Schumer, Program Manager 
Microsoft Corp. 

As the new Program Manager for Macintosh Languages 
here at Microsoft, let me thank Dave Kelly for the fine review you 
wrote in the February issue on our new interpreter and compiler 
and may I respond to some of the bugs you and your readers have 
uncovered and which you communicated to me in your recent 
letter. 

Terminal Program: We are actually aware of three seperate 
problems with the communications port. We are working to fix 
these problems. We have a patch for one of them. 

Default Window: Your right! The display of a default 
window is annoying in compiled programs. This will be ad- 
dressed in the next major release. 

Zoom Box Support: This will be added to the present method 
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of double-clicking on the title bar in the next major release. Ditto 
for the compiler. 

Large Code Size: We are investigating ways to shrink code 
size and hopefully will be addressing this in the next major 
release. It'S not unusual to expect a 3 to 1 expansion in any 
language from source to compiled form. However, I would like 
to see itreduced as much as possible. Sharing the runtime module 
with a number of programs can save 40K. 

HFS: Major enhancements to the way HFS is handled in both 
the interpreter and compiler will be addressed in the next major 
release. 

Undocumented features: TextEdit support was built-in to 
BASIC at the last minute mainly in response to one of your 
articles. It was too late to include in the manual but certainly will 
be documented further in the next revision of the manual. We 
would like to invite Dave Kelly and Dave Smith to discuss our 
future plans for MS Basic and to get any suggestions you have as 
to features you would like to see implemented. [We accept. Ok, 
gang, here is your chance! Send in your wish list on MS Basic and 
we will present them to Microsoft. -Ed] 

Turbo Bug 
Tim Votaw 
Anaheim, CA 

I stumbled across something recently that I can't seem to 
figure out so I thought I'd pass it along to you and your readers. 
Itseems that Turbo Pascal allows division by zero at compilation 
time and hence produces a nice system crash (ID 4) in your 
program, although the resume function seems to recover you. 

[We checked this error in the latest Turbo Pascal copy, 
version 1.00D, just sent yesterday to our offices. While this new 
version is supposed to fix some bugs with the floating point 
routines, it does not fix this one. Here is the program: 

program divbyzero; 

{$U-} 

{Turbo Pascal 1.00D version} 

uses MemTypes, QuickDraw, OSIntf, Toollntf, PasInOut, 
PasConsole; 

var 

thenbr,zero:integer; 
begin 
zero:=0; 
thenbr:=0 div zero; 
& executes ok!} 
writeln(thenbr); 
thenbr:=1 div zero; 
crash ID=04.} 
writeln(thenbr); 
end. 

When we ran this program, it compiles and executed! The 
first division by zero wrote “0” to the window, but the second one 
produced a system crash with ID 4. When we hit the resume 
button, Turbo then trapped the error and reported a division by 
zero error. We then compiled the program to disk and it also 
produced a nice stand alone application, that when executed, 
displays a nice system crash although the resume button returns 
to the Finder. The listing below is the same program in LS Pascal: 

PROGRAM divbyzero; 


{this line compiles 


{causes system 
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{LS Pascal Version} 


VAR 
thenbr, zero : integer; 
BEGIN 
showtext; {get default text window up} 
zero := 0; 


thenbr := 0 DIV zero; {This line won't compile!) 
writeln(thenbr); 

thenbr := 1 DIV zero; 

writeln(thenbr); 

END. 

We tried the same program in LS Pascal to see what it would 
do. The program correctly refused to compile at the first division 
by zero statement. We had to change zero toa 1 to get the program 
to compile and execute. Obviously, LS Pascal has better error 
checking at compile time. (See fig. 2) -Ed] 


Fig. 2 Catching potential run-time errors 


6 File Edit Project Run Det 
==> 15 turbo bug.pas 


"M 
| 


program divbyzero; 


var 
thenbr , zero : integer ; 


begin 
showtext; 

zero := 0; 

thenbr := O div zero; 

writeln(thenbr); 

thenbr := 1 div zero; (causes system cra 
writeln(thenbr); 

end. I 


Vol.3 No. 5 


Bob Murphy 
Vice-president 
Data Tailor, Inc. 
Makers of Trapeze 


I agree with Paul Zarchan (“Workstation Potential of the 
New Macs”, March 1987) that the Macintosh II and similar 
68020/68881 Macs can be used effectively for many CAD 
problems. However, the article uses the results from specific 
language implementations applied to a specific problem using a 
specific algorithm to make generalizations about the applicabil- 
ity of entire languages to CAD problems. One unjustified gener- 
alization is that FORTRAN and BASIC are fundamentally faster 
languages for simulations than C or Pascal. 
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Its also important to consider all relevant factors in solving 
a CAD problem. For example, many cases the use of slower, 
higher-precision math lets you use a very efficient algorithm 
which can't be used with faster, lower-precision math because 
round-off error would propagate to unacceptable levels. Gener- 
ally, the speed increase due to the better algorithm more than 
offsets the slower math, so that the "slower" language implemen- 
tation is actually faster for that particular problem. 

Some languages have features which will improve the 
efficiency of simulations if they're used properly. For example, 
sequential access of array values will usually be faster in C, if 
incremented pointers are used, than in FORTRAN using array 
indices. 

When comparing two language implementations, one 
which uses SANE, and the other which does not, it's important to 
recognize that hardware can play a big role in SANE's efficiency. 
I did a very naive implementation of the benchmark in Light- 
speed C 2.00n a Prodigy 4, using none of C's special features, and 
gotarunning time of 49 seconds, versus the articles 75. This may 
be due to the fact that I have the most recent Prodigy PROM 
revision, and Mr. Zarchan perhaps did not. Similar differences 
will be seen between the 64K and 128K ROM Macs due to 
changes in SANE. [And especially between the 128K ROMs and 
the 256K ROMS which have extensive SANE improvements. - 
Ed] 

Still Need Word Processors 
Anthony J. Oresteen 
Batavia, IL 

Withalltherecentinterest and talk on the new wave of word 
processors for the Mac, I have yet to find a SINGLE word 
processor that can perform the following very simple task. What 
I need is a word processor that can create simple text files with 
lines not exceeding 68 characters and smart enough to remember 
to insert a carriage return when it auto wraps a line. Do you know 
of any out there? 

Many of us have to talk to IBM mainframes that have 
archaic electronic mail and text editors. When I send documents 
to my mainframe, I am restricted to lines of 68 characters or less 
and each line must have a single carriage return. I write all of my 
reports on my Mac Plus and then send them out using SmartCom- 
тії. Many word processors let you set the line width. The 
problem is that when the line auto wraps, it does not insert a 
carriage return at the end of the line. Thus when I send the file, 
I cause a line overflow error with the host system with lines that 
auto wrapped. 

Note that the MacWrite solution of inserting a carriage 
return at the end of every line if you tell it to when you save it as 
ASCII then ends up putting two carriage returns for lines sepa- 
rating paragraphs, which is unacceptable. The best solution I 
have found is to use QUED 1.53, setting the font to Monoco 12, 
line width to 68 and use show invisibles to find lines without the 
needed carriage returns. I have to insert the carriage returns 
manually. It's a pain. I can have 24 point fonts, paste in graphics 
and print on a LaserWriter, but I can't create simple ASCII files. 
Why? 

[Your problem brings up an interesting philosophical de- 
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bate. What you have discovered is that what you see is what you 
get is not always what you want! There are good reasons why 
traditional word processing was done the way it was; to provide 
maximum flexibility in the specification of how lines of text are 
to be constructed. Nearly all the Mac word processors make 
assumptions about the text and paragraph construction in an 
effortto get maximum flexibility while retaining the WYSIWYG 
philosophy of the Macintosh. Perhaps placing formatting infor- 
mation into the text stream is not such a bad idea after all! As for 
me, I like a quick and dirty bang the words in kind of word 
processor that doesn't let the features get in the way of the typing. 
Which is why I'n writing my own version of MacWrite! I think 
the page layout features should remain in the layout program, not 
in the word processor. -Ed] 

Goodbye Kiss 

Michael Casteel 

Sunnyvale, CA 

With the perspective of a professional programmer, I was a 
little disappointed in the Tech Note by Dan Weston in your 
February issue, correcting the bug involving a "goodbye Kiss" 
received by his published desk accessory code. Mr. Weston's 
desk accessory crashed when receiving a goodbye kiss because 
he used a jump table which assumed that CSCode would always 
be between 64 and 73, but the goodbye kiss CSCode is -1. The 
Tech Note published a corrected listing which includes a special 
check for -1. The new code assumes that CSCode will always be 
either -1 or between 64 and 73. 

I wish you would have taken the opportunity to teach good 
(defensive) programming techniques. There is absolutely no 
need for a program to assume the range of inputs to a jump table, 
when it is so easy to ensure it. Before using a jump table, a good 
programmer should range check the input and if it is not in the 
expected range, DON'T JUMP! 

Just think, if Mr. Weston had applied this principle in the 
first place, the goodbye kiss still wouldn't work, but at least his 
DA wouldn't have bombed the whole Macintosh! Who knows 
what new CSCode values the Macintosh II might bring? 

APDA Problems 
Tim Cuthbertson 
Pelham, AL 

Your February issue contained a couple of favorable refer- 
ences to the Apple Programmer's and Developer's Association. I 
have had nothing but trouble in my dealings with them. I 
responded to their Ad in MacTutor last August, sending a $20 
check to pay for membership. In September, I received only an 
invoice noting a credit of $20 to my "non-member" account. I 
waited a while to see if they would send me anything else, 
expecting membership materials or offers of products, but noth- 
ing. Finally I wrote a letter of complaint, but again, no response. 
I finally broke down and made the long distance phone call only 
to be told I had to call before 3:00, not ten minutes after. 

I have stuck with my original 512K Mac for two years but 
the recent LS C upgrade seems to have rendered it obsolete. My 
400K drives just don't cut it. The local Apple dealer wants $798 
to upgrade the machine they sold me for $2600 to a machine level 
that currently markets for $1900! That really hurts. 
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Professionally Iam aSystems Analyst with IBM mainframe 
experience. But, I have become very frustrated trying to learn to 
program this [*darn*] machine. Your magazine and Scott 
Kanaster's book How to Write [Debug] Macintosh Software are 
the only lights at the end of the tunnel. Keep up the good work. 

[We have received several complaints about the slow re- 
sponse of APDA. Whenever you create a monopoly, as Apple has 
done with APDA, you create problems. APDA has simply been 
undermanned for the response it has received. It is easy for Apple 
to absolve itself of all responsibility for developer support and 
place it onto APDA's shoulders, but quite another thing for 
APDA to try and cope with the problem. This may be a continu- 
ing problem for APDA as it sits between hordes of hungry 
developers and the fickle whims of Apple marketing. 

As far as the Mac goes, the 512K Mac is dead. Long live the 
Mac Plus and it's decendents. However, we think Apple should 
make the upgrade path from a 512K Mac to a Mac Plus much 
more reasonable. The Mac Plus is the new base line of technology 
for the Mac family and as such, Apple should speed everyone's 
conversion to the new standard with a big price break upgrade 
program like they did for Lisa. -Ed] 

Toolbox Tricks in C 
R.J. Hall 
Seattle, WA 

I agree with M. Decombe's letter in the February issue. A 
Trick Corner would be a most useful addition to your excellent 
magazine. In fact, here's one of my favorite non-toolbox routines. 
Call it after dealing with a mouse down event when you want to 
check for a double-click. If the mouse is pressed again inside 
inRect and during the double-click interval, the routine returns 
TRUE. 

Check. DoubleC inRect) 

Весі  *inRect; 


( 


long end. Time; 
Point eventPoint; 
EventRecord dcEvent; 


end_Time = TickCount() + GetDblTimeC); 
while ClEventAvailC "mUpMask, & dcEvent)) 
if (TickCount(C) > end. Time) 
return(FALSE); // OUT OF TIME 


if CdcEvent.what equals mouseDown) 
( 
BlockMove(&dcEvent where, &eventPoint, 
sizeof (Point)); 
Global ToLocalC&eventPoint); 
if (PtInRectC(&eventPoint, inRect?) 
( 
F lushEvents(mDownMask ); 
return( TRUE); 


//Note! 

/ /DOUBLE-CLICKED 
) 

( 

return(false); 


) 
The routine 'GetBdlTime()' is defined in Using the Macin- 
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tosh Toolbox with C' on page 201. By the way, there are several 
RMaker DITL items undocumented in the LS C manual. Try 
using the following: iconItem, picItem, userItem and resCltem! 
[There are several sources for RMaker documentation including 
the LS manuals, back issues of Mactutor on resource formats, 
Consulair C's new manuals, and I believe Apple tech notes. -Ed] 


Microsoft Explains MS DOS Limitations 


Microsoft released a press kit today that explains the features 
of both its MS DOS 3.3 product and the new MS OS/2 product 
for the new IBM System /2 computers. As reported in the press, 
this new IBM operating system for the Intel 386 family proces- 
sors is not expected to be ready until 1988! Why are we mention- 
ing it here in Mactutor? Because it is instructive to understand the 
differences between the IBM System/2 model 80, a 386 machine, 
and the Macintosh II, a68020 machine. These two computers are 
going to be going head to head with each other and a better 
appreciation of the Apple design can be obtained if you under- 
stand the background of the IBM machine. Apparently Microsoft 
has taken a lot of flack over MS DOS 3.x and has included some 
interesting product history on the Intel chip family that clears up 
many mysteries of the IBM personal computer while at the same 
time, brings a greater appreciation for the design of the Mac II. 

MS OS/2 provides for up to 16 megs of real memory and 1 
gigabyte of virtual memory. It provides for a priority-based pre- 
emptive multi-tasking scheme with inter-task communication. It 
supports both “real” and "protected" mode of the 286 and 386 
chips, to help software compatibility, but multi-tasking requires 
applications be able to run in protected mode. 

Now compare this with the Mac II OS which is available 
now. The Mac II supports 8 megabytes in 24-bit mode while the 
IBM family is generally limited to 640К up and down the line. In 
32 bit mode, the Mac II will support up to 1 gigabyte although 
chip technology will probably make 128 megs a practical limit 
for real memory using 16 megabyte memory chips. And of 
course, we haven't even mentioned the NuBus slots, which can 
support an additional 256 megabytes per slot in "super slot" 
mode. The next Finder will supporta practical implementation of 
quasi multi-tasking that works up and down the Mac product line 
and does not require the PMMU memory management chip. And 
this will be released far before OS/2 is out. Finally, once the Mac 
world switches to 32 bit mode, a full priority based multi-tasking 
Finder could be provided using the PMMU in probably the same 
time frame as the release of OS/2. It is my guess that Apple is 
working to that end. The following history on the 8086 family is 
taken from the Microsoft press release. 

The 8086 is Intel’s original 16-bit microcomputer. It in- 
cluded a number of features for backward compatibility with the 
8-bit Intel 8080 that in many ways constrained its design. One of 
these is the use of a segment register from which 4 bits are added 
to the 16 bit offset to provide a 20 bit address. This limits the 8086 
to 1 megabyte of memory, which is addressed not directly, but by 
manipulation of this segment register. Contrast this with the 
68000 which has 24 bit address registers that can directly address 
16 megabytes. 
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With their PC, IBM made certain fundamental decisions as 
to the memory architecture of the machine: they took the avail- 
able one megabyte of address space and decided to reserve all the 
memory above 640Kb for use by the system. Within the 640Kb 
to 1Mbrange lie such things as the ROM BIOS, the video display 
memory and other reserved areas. This is where the often 
discussed, and often misunderstood 640K b limit arises: the DOS 
and all the applications software has to reside and operate in the 
0 to 640 Kb address range: anyone who decides to use areas of 
memory above the 640Kb limit runs the risk of being incompat- 
ible with any future release of hardware or software products by 
IBM for the PC. 

The 8086 has no memory or device protection inherent to the 
processor architecture. And the PC design does not provide any. 
This makes it very difficult to implement a multi-tasking operat- 
ing system because many applications will directly reprogram 
hardware devices such as the system timer and floppy disk 
controller, and write directly to the video screen for better video 
performance. The operating system thus is unable to control the 
situation of two or more applications writing to the screen at the 
same time. Hence MS DOS 3.x is limited to 640Kb of memory 
and single-tasking operation. 

The Intel 286 chip adds protection capabilities lacking in the 
8086 and increases the memory it can address to 16Mb, same as 
the 68000. Unfortunately, Intel did not do a very good job with 
the 286: the additional capabilities are only available to programs 
which execute in so called ‘protected mode’ as opposed to ‘real’ 
mode which emulates the 8086 (including the 1Mb address 
limitation and no protection). Now the kicker! The real and 
protected modes of the 80286 are incompatible: software written 
torun inone mode will generally not work if the chip is executing 
in the other mode! In particular, MS DOS itself runs in real mode 
and thus cannot make use of either protected mode nor additional 
memory beyond the 640K barrier! If it had been made compatible 
with the protected mode features, then all the software base on the 
PC AT, and PC XT would not have run in that mode due to the 
incompatibility between real and protect modes. Thus the deci- 
sion was made to defer support of protected mode until a later 
release of DOS. Contrast this "painted in a corner" situation with 
the 68000 family which is fully compatible up and down the line. 
But the situation gets worse. 

One of the major incompatibilities between real and protect 
mode is that the memory addressing model changes! In protect 
mode, the segment register is interpreted in an entirely different 
way. Thus any application program which manipulates segment 
registers on an 8086 (and many of them do) will have to be 
rewritten to conform with the segment register usage rules of 286 
protect mode. Hence an incompatibility problem exists trying to 
write software that both runs on PC's and 286 based machines. 

This brings us to the Intel 386 chip. This chip adds yet 
another mode of operation while also emulating both the 8086 
‘real’ mode and the 286 ‘protect’ mode architecture. The chip 
provides the foundations for building yet another operating 
system that could solve all the compatibility problems, but this is 
a significant development effort and the problems are certainly 
not solved by the chip alone. The modes of the 386 are real mode 
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(emulates the 8086 exactly, 1 Mb address limit and segment 
registers and is the default mode of the chip), 8086 virtual mode 
(another 8086 emulation mode, but with a few protection features 
for supporting several applications each with their own virtual 
machine), 286 virtual mode (emulates the 286 protect mode) and 
finally, the only one of real interest, 386 virtual mode (allows full 
32-bit linear addressing similar to the architecture of the Motor- 
ola 68000. ) 

The new OS/2 operating system will support 80286 and 
80386 protected mode, virtual memory, multi-tasking and will 
solve compatibility differences across all machines running OS/ 
2. And of course it includes a version of windows that uses 
overlapping windows instead of tiled windows. The IBM version 
of OS/2 is rumored to also include some mainframe communica- 
tions support. Clearly, one of the reasons for the delay is they had 
to re-write the entire operating system! This should give Apple 
plenty of opportunity to continue to upgrade the Finder to provide 
the same capabilities, especially in the area of multi-tasking and 
virtual memory addressing independent of the applications run- 
ning under it. Lets hope Apple takes advantage of the next six 
months to do just that. 


Say That Again? 
Phil Barnard 


Tasmania, Australia 
I hate your magazine. 


I want you to know that MacTutor has been responsible for 
untold numbers of long and sleepless nights typing in published 
programs. 

• Ihave had fights with the wife and kids for my continu- 
ous reading at the dinner table. 

* I have had arguments at work with people trying keep my 
MacTutors for themselves. 

• I am reduced to programming in Forth to the exclusion 
of everything but eating and drinking. 

Today I even had hassles wit the bank clerk rusing to convert 
Australian to US dollars for the enclosed subscription renewal! 
It really is all your and Jórg Langowski’s fault! 


P.S. Well done! 
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Pagemaker 2.0 Incompatible with 1.2 
David E. Smith 
Editor 
Aldus Corp. released version 2.0 of Pagemaker today and 
MacTutor has found that version 2.0 is incompatible with version 
1.2 for placing formatted MacWrite files. Under version 1.2, the 
left margin setting of MacWrite has always been ignored unless 
the command key is held down, when reflowing formatted 
MacWrite files into Pagemaker columns. This has become a 
feature, since it is very difficult to work with a MacWrite window 
with the left margin set at O. Under version 2.0, this left margin 
setting is now automatically picked up by Pagemaker and the 
entire column of text is indented by this amount. Since there is no 
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way to stop this indentation, in order to get Mac Write documents 
to correctly reflow into Pagemaker columns, you must go back 
and re-format all of your MacWrite ruler settings to a left margin 
of 0. Even for a single large document, this can be a job! And for 
the thousands of documents formatted over the last two years, 
impossible! Since Aldus has indicated they do not intend to 
change this, unless forced by the marketplace, MacTutor is 
encouraging a letter writing campaign to force the addition of a 
dialog option to turn off automatic indentation of MacWrite 
formatted files in version 2.0. Please write to Paul Brainerd at 
Aldus, 411 First Ave. South, Suite 200, Seattle, WA 98104. 
MacTutor will be very grateful. 
TML Pascal and SANE 
Alan Engard 
Costa Mesa, CA 


I'm having a hair-pulling experience with TML Pascal (and/ 
or SANE) and hope someone out there can help. The “Тап” and 
"XpwrY" calls to SANE fail consistently. It creates an Address 
Error or Illegal Instruction Error depending on the individual 
program. The failure occurs regardless of whether the parame- 
ters are constants or variables, and occur in both plain-vanilla 
Pascal and all-Mac Pascal code. 

Following is an example: 


program test (input,output); 

uses macint f, sane int f; 

var 
result :real; 

begin 
writeln(“Tangent:’); 
result:=Tan(3.1415926536); {TML crashes) 
writeln(result); 

end. 


And I do know that at least some calls to SANE do work 
(although they аге all non-calculation oriented): Num2Str and 
ClassExtended. 

MacUser (as early as the February issue) listed the current 
version of TML Pascal as 2.01, while I have 2.0--і this right? 
If so, does this bug(?) still exist and what else has been fixed/ 
added/changed? (On that note I would like to suggest that you 
mention development tool updates and briefly list their changes.) 
Thanks for all of your invaluable information—keep up the good 
work! 

[We tried the example in Lightspeed Pascal and it ran a 
tangent function from SANE with no problems. I suggest you 


Tangent of Pi = 
0.000000000010 


КЭ 
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contact TML about updating to version 2.01 and ask them about 
this bug. The update problem requires a full time person to keep 
up with it. We haven't found the time or money to hire such a 
person yet, but I agree the job is needed. -Ed] 

uses sane; 


PROCEDURE doUser; (LS Pascal exemple) 
VAR 
result : extended; 
stri : str255; 
str2  : DecStr; 
f : DecForm; 
BEGIN 
result := Tan(3. 1415926536); 
f.style := FixedDecimal; 
f.digits := 12; 
Num2Str(f, result, str2); 
stri := ‘Tangent of Pi = '; 
doMessage(str1, str2, '', °’); 
END, 


McFace News 
Dan Kampeler 
Urbana, IL 


[Chuck Bouldin is preparing a Fortran article on McFace. 
Unfortunately the article didn't get to MacTutor before Chuck 
went on vacation, which leaves us in the humorous position of 
publishing the rebuttal before the review! However, Mr. Kam- 
peier has some good points, and McFace is a solid product so here 
is the author's comments to a review no one has seen yet! -Ed] 

First, I would like to thank Chuck Bouldin for taking the time 
to review McFace. Chuck is an avid user of McFace, and has 
contributed to the enhancement of McFace via his many com- 
ments and suggestions. I would also like, however, to provide a 
further explanation or clarification of the two major criticisms 
which Chuck made of McFace: (1) its relatively large size, and 
(2) its use of numbers as arguments in calls to McFace. 

(1) One problem with the Absoft (Microsoft) Fortran com- 
piler for the Mac is that the object code which it generates is at 
least twice as large as that generated by the Pascal or C compilers 
for the equivalent source code. This may be a trade-off for the 
execution speed, but I've also heard that the compiler is simply 
not very efficient with respect to the object code it generates. 
Now if you are stuck using such a compiler, the obvious thing to 
avoid is duplicating source code from program to program, and 
this is exactly what McFace does for you: it provides a single 
subroutine which can be used by many different Fortran pro- 
grams on the same disk. The second reason why McFace is so 
large is simply that it does so much for you. 

It contains code for file handling, text editing, picture han- 
dling, etc., as well as functions such as “Сору Table" (replace 
spaces with tab), search & replace, auto-indent, etc. If you use 
Fortran to create a program with most of the functionality of 
McFace, I guarantee that it will be at least as large as McFace. 
Finally, memory is going to continue to get cheaper, the Mac 
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toolbox is going to continue to get more powerful, and McFace 
is going to inevitably get bigger as user expectations rise ever 
higher. (Look what has happened to the size of MS Word!) 

(2) I experimented with many different methods of passing 
information between the calling program and McFace, and 
settled on a scheme with three levels: (a) direct "macro" 
commands are passed as arguments in the subroutine call, (b) 
often used variables are shared in a common block with the 
calling program, and (c) seldom used variables are stored in an 
array which the programmer can access as needed. Passing 
macro commands as numbers (versus integer variable names as 
recommended by Chuck) is preferred by most of the active users 
of McFace to whom Ihave talked. The source is cleaner, and their 
are simply not that many different macro commands to remem- 
ber. Moreover, nearly all of the commands simply correspond 
toa McFace menu and item number, so that anyone familiar with 
the McFace Apple, File, Edit, and Window menus will also 
automatically know many of the macro command combinations. 
Furthermore, use of integer variable names for numbers is not as 
easy as it sounds since many of the McFace menu items are 
context sensitive (depend on which window is at front), and some 
menus are of variable length (depend on number of windows in 
use). Finally, nothing prevents a McFace user from simply 
creating integer variable names to use in place of numbers in calls 
to McFace. 

McFace continues to evolve. Version 3.0 will ship sometime 
early this summer and should be compatible with the Mac II 
(Absoft was having trouble with some toolbox calls on the Mac 
II with its current release). My continuing goal is to put as much 
generic stuff into McFace as possible to facilitate the rapid 
development of fully Mac-like programs in a minimum amount 
of time using Fortran. 

W.J. Meyers 
Newsletter Editor 
Hughes Mac-HAC’ers 

Thank you for allowing us to reprint Loy Spurlock’s 
comments оп the Mac's power supply problems from a past issue 
of MacTutor. I was told by Loy that you have given your 
approval to concurrently publish his article providing we ac- 
knowledged your permission to reprint at the beginning of the 
article. A copy of our newsletter is enclosed to prove that we 
complied with your wishes. 

By the way, if you are still keeping tabs on the problems 
user's are having with their SCSI drives, please put my name on 
the list. I am having one hell of a time with my ProApp 20 
drive(s), but let me follow through to a conclusion before I tell 
you the whole story. 

32k Segment Limit-Revisited 
S.C. Kim Hunter 
Mission Viejo, CA 


In MacTutor, March 87, I made a comment regarding a 
“fundamental” limit of the 32k that is imposed in many of the 
compilers for the Mac, mainly Pascal, and pointed out that 
MacFortran doesn’t have any of these limits, simply because 
Absoft chose to ignore the Mac ROM segment loader when they 
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wrote their compiler (actually just ported it from something else). 

To confirm my suppositions, I ran a test program in both 
Lightspeed Pascal and MacFortran. Listings are enclosed. In 
Lightspeed Pascal, one can define an array of integers up to 
1..15497 in the global variable part, and in a procedure, up to 
1..16375. Integers in Lightspeed Pascal are each two bytes, so 
these limits are close to 32k (which should be 32768 bytes, or 
1..16384 integers). If the dimensions are increased by 1 more 
than these limits, the compiler politely puts up an error message 
advising one of three messages: 1) "Project has more than 32k 
of globals”, 2) “Available memory for variables declared at this 
level has been exhausted”, or 3) “Variables of this type would be 
too large". At which point these messages appear is shown in the 
Lightspeed Pascal listing. 

The same program done in MacFortran, and constricting 
integers to 2 bytes (integer*2-the defaultis 4 bytes), compiles and 
runs perfectly at the dimensions well over those of Lightspeed 
Pascal version. I ran the integer array dimension up to about 
150,000 before running in to problems (on a 512k Mac XL). 
Unlike the polite messages of Lightspeed Pascal, MacFortran 
just overwrites and bombs (freeze, crash to Macsbug, the gamit, 
out of control). The compiler has no messages, friendly or 
otherwise, compiling and dimension with no grips. Only when 
the program runs do you know if you exceeded the memory limit. 
If you add more RAM, the problem goes away till you pump up 
to the new limit. 

Lightspeed Pascal does edit, compile, run cycle in about 21 
sec, good or bomb (politely). MacFortran, if you insert an 
“execute(‘QUED 1.57)” to auto re-enter the editor takes about 
1:20 min:sec for a good cycle, 2:40 min:sec for a crash/reboot on 
a Mac XL. So you take your choice: small, quick, polite bytes 
with Lightspeed Pascal, or Russian Roulette chomps with Mac- 
Fortran. 

I have passed these questions to Apple Macintosh Technical 
Support. They are beyond my limited scope as a “high level 
programmer". Only someone who has actually read and under- 
stood Inside Macintosh and actual been inside a Macintosh could 
answer the questions. I am too big and fat to fit that spec. Andy 
Hertzfeld is small but fat (and cute! but that doesn't count except 
when his software crashes-then he's not so cute!). 

We soon will have Macs with 4 megabytes (some have 
them now). Are weonly allowed to swallow them in 32k chunks? 
Lets see, 4,096,000 divided by 32,768 is... How many chunks? 

Don'texpectthe answer to come from Think Technologies. 
At $89 per package, they can hardly pay for Steve Stein to answer 
the phone (which he now doesn't seem to be doing). Only Apple 
with $500 mill in the bank can afford to pickup the phone. 
Hello?... Hello?... MacTech?... Is anyone there? 

[The problem is that many compiler makers copied the 
segment loader technique for addressing code segments, which 
is to use a base address with an offset to the desired segment. I'll 
take a guess and say the addressing mode they are using is PC 
with displacement. On the 68000, that particular form of address- 
ing limits the displacement offset value to a 16 bit sign-extended 
integer, which is the source of the 32K limit. The 68020 allows 
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this displacement to be a full 32 bits, so this restriction is not 
present. But the more important point is, they should not have 
used this particular addressing mode. The 68000 obviously 
offers a variety of addressing modes for directly reaching any- 
thing in the 16 meg memory space. -Ed] 

03/25/87 22:56 LSP test32kprog 

program test32k; (32k limit should be 32768 bytes) 
(Lightspeed Pascal data structure limits.) 

(Exceeding the limits incurs polite compiler error 
messages) 

(Edit, Compile, Run time: 21 sec,) 

(regardless if data size OK or too big) 

(S.C. Kim Huner for MacTutor) 


ver 

i:array[ 1.. 15497] of integer; ( max global=30994 
bytes} 
(1..15498 generates:  ".more than 32k bytes of glo- 
bals.") 


{Also just adjust another variable, "c :char;"-same 
message) 


procedure xx; 
var 
i:errey[1..163751 of integer; ( max ргос=32750 
bytes) 


( 1..16376 to 1..16383 generates: } 

( "Available memory for variables declared at this 
level has been exhausted} 

( 1..16384 generates: "Variables of this type would be 
too large. ”} 


begin 

end; 
begin 
end. 
test32k. for Wed, Mar 25, 1987 

program test32k 
MacFortran, Version 2.2 
MacFortran data structures limited only by RAM. 
if limit exceeded, MacFortran just crashes. 
Mac XL Edit, Compile, Run time: 1:30 min:sec if OK 
Edit, Compile, Run, Crash, Reboot time: 
2:40* min:sec if too big 

S.C. Kim Hunter for MacTutor 


C») C) C) C) C»? СОО C 


integer*2 i 
dimension 1( 150000) ! 150000 OK 

C At 160000- 170000, things deteriorate and freeze ог 
crash 

C on Mac XL with 512k. 
away. 


Add more RAM, problem goes 
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call xx 

write(*,*)“Im Ok, so far. 
pause 

executeC^QUED 1.5”) 

end 


(But maybe not! >’ 


subroutine xx 
integer*2 ii 
dimension 11( 16376) 


C 16376=1 more than Lightspeed Pascal can do, 
C didnt try more. 


end 
Park Your Head 
Serge Froment 
Québec, Canada 


There is much confusion about the hard disk head parking. 
Every hard disk manufacturer seems to have his own opinion and 
way of doing it. Here is some questions I would like to be 
clarified. 

When I bought the DataFrame hard disk, about a year ago, 
the manual told me that I must issue the “shutdown” command 
since the command does park the head of the DataFrame. 

Recently, I received a new version of the DataFrame 
software, and the “read me" file says that I must use the new 
"SuperParker" program to park the head before moving the hard 
disk. One question arises: did the "shutdown" command really 
park the head? 

What is “head parking"? The first documentation of the 
DataFrame said that it “moves the head to an unused portion of 
the disk". The new documentation says that “it may take longer 
for the hard disk to boot after head parking since the drive have 
to recalibrate the head to former position", which sounds more 
complicated than just moving the head to an unused portion of the 
disk. 

Ialso saw recent public domain head parker programs. The 
documentation says that those programs issue a SCSI "stop" 
command. Does that command have a standard effect on every 
SCSI hard disk? It seems not: when I use those programs on my 
DataFrame, the disk boots faster than when I use the Supermac's 
SuperParker. 

I recently bought a Macintosh SE with internal hard disk. 
The manual says nothing about head parking in the section 
talking about the internal drive. There is now a real shutdown" 
command along with the new "restart" command. Does the new 
"shutdown" command do anything more than avoiding you to 
rush beating the rebooting action? In the section about "caring 
for your Macintosh SE", the documentation only says that when 
moving the Macintosh, you “should use the materials that the 
computer came packed in. If the system includes the internal 
hard disk, the canvas cases manufactured for older Macintosh 
units are probably not sufficient protection." Does it mean that 
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the Macintosh is now so business oriented that it should not leave 
the office? What about the passenger seat of my car, with the 
safety belt buckled up? Should I affix a “computer on board" sign 
in the rear of my car? 

The Macintosh SE is a great machine... but I hate the key- 
board. It reminds me of the worst IBM PC clones. The feeling 
isawful, and it makes me do many typing errors: the keys I strike 
are often not entered, and I occasionally strike the “4” key instead 
of the space bar. The absence’ of the right sided "option" key is 
painful when typing left sided special symbols. The original 
Macintosh keyboard layout was great. So great that even IBM 
copied its basic layout on the new PC models. Why change the 
position of keys on every new Macintosh model? Since there is 
a new "restart" key over the numerals, it would have been 
possible to place the cursor and the "escape" keys there also and 
keep everything else into place... 

A final word about international resources. The original 
INTL resources contains the format of dates and the string for 
writing every day of the week and month by name. It also 
contains a single abbreviation size for short date format. There 
is a flaw in this design: in French, the days of the week 
abbreviation uses 3 characters. So far, it'S ok. The problem 
comes when applying a 3-char abbreviation to month names: in 
French, June and July spell “juin” and “juillet”; so the abbrevia- 
tion is “jui” for both. Using a 4-char abbreviation for everything 
looks ugly, especially for the days of the week. The French 
localization uses a 3-char abbreviation despite the ambiguity; the 
French Canadian uses a 4-char one despite the ugliness. The true 
solution would be to have an abbreviation size for every day and 
month name. I have not received yet the localized version of 
system 4.0. Iknow ti allows writing with all scripts of the world, 
including Arabic, Japanese and Chinese. I strongly hope it will 
also solve that old Roman script problem. 

Yes Virginia, You Can Find Yourself 
David M. Lane, President 
Clear Lake Research 
Houston, TX 

Just a note about HFS compatibility and the MS-BASIC 
compiler. It turns out it is possible to create stand alone applica- 
tions using libraries from BASIC that work even if the user 
changes the application's name. Unfortunately, the method is 
very poorly documented, alluded to only in one of the READ ME 
files distributed with the compiler. First you move the necessary 
library statements into the application. Then with PEEK state- 
ments you determine the name of the current application. You 
then use this name in the library statement. For example, 


Appname A$ 
LIBRARY А$ 
REM rest of the program follows: 


END 

SUB AppName (theName$) STATIC 
theN: am e$= 9999 
CurAppName-&H910 
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i%=PEEK(CurAppName) 
FOR j%=1 TO i% 
theName$=theName$+CHR$(PEEK(CurA ppName+j%) 
NEXT j% 
END SUB 


will work regardless of the folder the program is in or what the 
name of the program is. 

We have been distributing a statistical program (CLR 
ANOV A) incompiled MS-BASIC since December. It is a stand 
alone application and is fully HFS compatible. 

Number Crunching on the Mac 
Louis M. Pecora 
Washington,D.C. 


Enclosed is a $30 check for a year's subscription to MacTu- 
tor. Do you have a list or index of past articles so I can decide 
which back issues to order? [We're working on it...] 

Enclosed with this letter and paymentis an “open letter" about 
number crunching. It was inspired by a recent very good article 
by P. Zarchan in MacTutor and partly by my own experiences. 

Most working engineers and scientists would like to have a 
work station on their desktops. At this time, most cannot afford 
aSun, Apollo, or VAX. However, for many applications the Mac 
plus or its descendents can prove to be effective tools. The 
exception to this is for number crunching. Two main problems 
which appear to surface on this topic are the SANE routines and 
available scientific programming languages. The particular 
questions I raise here cover these, along with some other ques- 
tions. The range is from Mac-specific to general computer 
software questions. I include them all because, in the long run, 
they will all affect the Mac and its descendents. My preference 
is for C, but those who prefer other structured languages can often 
substitute their name in place of "C" in what follows. 

Two recent articles!? show that use of SANE floating point 
routines can slow number crunching on the Mac to a crawl. 
Microsoft FORTRAN uses its own IEEE routines which, al- 
though less accurate than SANE, can blaze through number 
crunching. However, Microsoft FORTRAN is not the answer, as 
I state below. The real question is are there other floating point 
routines available for the Mac which can be accessed by other 
languages, especially the structured ones: c, Pascal, Modula-2, 
etc? I've heard that Motorola has its own routines and that these 
are available to some Forth packages. Can they be made 
available to other language packages? Are there floating point 
routines available which specifically use the 68881 coprocessor? 
This is an item sure to become a standard on future Macs.[Jórg 
Langowski published a complete 32 bit floating point package in 
a past issue of MacTutor that addresses these concerns. It could 
be modified to call the 68881 directly. SANE on the Mac II is 
patched to use the 68881 independent of your application and that 
speeds it up four fold at least. -Ed] 

Another aspect of number crunching is the use of large data 
arrays. Often these cannot fit in RAM and use of virtual memory 
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(disk space) must be made. Only Microsoft FORTRAN, to my 
knowledge, can do this. Are there other language packages 
which can do this? [The 32K segment limit in most compilers 
(including MPW) means you have to construct your own data 
structures using a handle to point to a block of memory. That 
block could be made virtual by designing your program to do so. 
-Ed] 

From what I’ve said above, one might think that Microsoft 
FORTRAN is the answer to number crunching questions. But 
anyone, especially a Mac user, who has used Microsoft FOR- 
TRAN knows that it is buggy and clunky. It does not easily 
deliver what it promises. Experiences at our lab is generally that 
programs written in Microsoft FORTRAN often take 2 to 5 times 
longerto debug than programs in C or Pascal oreven FORTRAN 
on a VAX. Access to the Mac toolbox is cumbersome. Some 
experiences have been so frustrating that people have just given 
up. 

Some of the problems are with Microsoft FORTRAN itself 
and some stem from just plain FORTRAN. Most programmers 
recognize that FORTRAN is an awkward beast which is used 
only because of inertia and the fact that nothing has appeared to 
take its place*. 

Recently, an enhanced version of C (С++) has been released 
by AT&T labs. It appears to have many features which are more 
effective and efficient than any C counterpart. These include 
items of interest to number crunchers: vectors, matrices, easy I/ 
O, type checking, etc. Is there a version of C++ for the Mac? If 
not, C with better floating point routines and the programs “lint” 
would be a good start for number crunching on a Mac. Is there 
a version of "lint" for the Mac? 

Finally, in a more general vein, is there a better scientific 
language available now or in the works which takes the best 
structured languages like C and the best of FORTRAN (type 
checking, floating point over- and under flow, virtual arrays, 
complex numbers, etc.) and combines them?? 

Many of the above questions are crucial for the Mac to gain 
a true foothold on most engineer's and scientist's desktops. The 
hardware is there. Except for the 68881 floating point coproces- 
sor, the above are software questions. I'm sure a great many 
scientists and engineers, besides myself, are interested in the 
answers. 


"Footnotes": 

1. MacTutor, March 1987, pp. 15-22 

2. MacWorld, one of the 1986 issues reviewing Microsoft 
FORTRAN 

3. I haven't looked into this yet, but I am advised that CIS 
(the MacForth people in Rockville, MD) are using the Motorola 
routines. 

4. Iam ignoring ALGOL here. IBM has made sure that, in 
the U.S.A., FORTRAN is the "preferred" language for scientific 
programming. I understand it's different in Europe where 
ALGOL is more readily available. 

More 68020 Benchmarks 
Chuck Bouldin 
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Bethesda, MD 


A few comments about the “МасСай” article in the March 
issue. I think this is a very good article, since it shows the 
potential of the upgraded Macs as true number-crunchers. If 
anything, I think the article understates the speed of a 68020- 
68881 for several reasons. 

First, neither the Basic nor the Fortran benchmarks contain 
any transcendental operations (sin, cos, etc. ). Surprisingly 
enough, such functionsare handled ona V AX as subroutine calls, 
while the 020/881 Fortran has inline calls to the 881. with clock 
rates of 12-16 mHz on 020/881 systems, benchmarks that are 
heavily loaded with transcendental functions actually run 
FASTER than a VAX 11/780. Also, the 881 will deliver 80 bit 
precision, where the VAX ( in standard REAL*8) gives 64 bit 
precision. 

Second, neither of the benchmarks uses large data arrays. 
Whenarrays getlarger than 64K, the performance of the 020/881 
systems goes up a lot relative to the segmented architecture of 
80386 or 80286 systems. In fact, when large arrays are manipu- 
lated, as in matrix inversions or the Sieve benchmark for finding, 
say, the primes up to 80,000, then a stock Macintosh will outrun 
a PC “AT”. To be fair to the VAX, it should be pointed out that 
the VAX will improve over the 020 on benchmarks with large 
data structures, as the VAX does a better job of addressing the 
data structures. 

It is also interesting to compare the performance of the Mac 
on the Whetstone benchmark, which mostly tests the speed of the 
floating point operations. The result are: (here, bigger numbers 
are better, i.e., faster computer) 


VAX 11/780 (1) 1100 
Mac-+/Absoft Mac Fortran (2) 41 
Mac+/Novy 020/881 upgrade (3) 214 
Mac+/Prodigy 4 upgrade (4) 500 
Compaq 386/ Lahey Fortran (5) 232 
Compaq deskpro 286/Lahey (6) 98 


Comments on the hardware/software: 

(1) Unloaded Vax 11-780 with VMS 4.x and latest release of 
the Fortran compiler. 

(2) Standard Macintosh with Absoft/Microsoft Compiler 

(3) Мас+ upgraded with Novy 68020/881 board, running 
Absoft MacFortran 020 compiler. Clock rate is still 8 MHz and 
data path is still 16 bits. 

(4) Mac- upgraded with Prodigy 4 running Absoft MacFor- 
tran 020 compiler. Clock rate is 16 MHz and data path is 32 bits. 
The factor of 2 over the Novy board is from clock rate increase 
and bus bandwidth. Except for the Mac’s infamous “video 
refresh through the CPU" this benchmark would be closer to 
750K whetstones. The Prodigy Prime and the Rye 020/881 
upgrades should provide essentially the same performance. 

(5) Compaq 386. Uses 16 MHz 80386 with hardware floating 
point supplied by a 12 MHz 80287, since there is, as yet, no 
available 80387. Lah’y Fortran compiler. 

(6) Compaq Deskpro 286, 80286/80287 running at 8 MHz. 
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Lahey Fortran compiler. 


I think it is very interesting that, with а $750 upgrade, a Мас+ 
will deliver virtually the same number-crunching capability as 
the very best ($7000) MS-DOS computer that is available. With 
more elaborate upgrades, that widen data path to 32 bits, and 
increase the CPU clock rate, the Mac gets even faster. The results 
are in good agreement with the conclusion in the article that the 
Mac II or upgraded Mac+ can be expected to perform at ~1/2 of 
VAX level. 

Finally, a few minor quibbles with the article. What is meant 
by an "improved" PC? Why does the use of an 80287 with an 
AT only change the speed of the Butterworth benchmark from 39 
to 35 seconds, while it changes the results on an improved PC 
from 75 to 40 seconds? Could we also get the speed of the 
Compaq 386 on the Butterworth benchmark? 

The most serious flaw in using the Macintosh for CAD work 
is that many languages have 32K segmentation limit! As you 
pointed out, Apple effectively trashed Motorola's clean linear 
address space and made it into a segmented Intel-style address 
space. I think that MacTutor should address this question in 
detail. Are there any C or Pascal compilers that will allow arrays 
or code segments larger than 32K? [If there is, MacTutor will 
offer a free ad space for the first good Pascal compiler that 
eliminates this restriction. -Ed] 

Hanover Fair Report 
Christoph Sold 
West Germany 


First, Iapologize for my poor English. Yesterday I was at the 
Hanover fair CeBit at Apple and have seen the two new Mac's 
and some new software. I was surprised by the new capabilities 
of these machines. I think only a few people from America were 
there, so I write what I have seen to you. 

First the hardware: There were —as said above— two new 
Macintoshes: The “little” Macintosh SE and the “big” Macin- 
tosh II. First I describe my impression on the Macintosh SE. It 
was ready built and —as Apple announces— now available. Its 
main difference to the Macintosh Plus is a slot, and the possibility 
to fit a second disk drive or a hard disk in. But the important 
difference is the change of priority between RAM access from 
the CPU and the video chip: This speeds the Mac SE up by 3096 
against a Macintosh Plus. 

Now the (seen) facts about the Macintosh II: It comes up 
with an 68020, hard disk built in and has no built-in monitor. 
Apple shows us two kinds of monitors: Two black and white 
ones, one of these shown with a resolution of 640x480 and a size 
of 12"; and one RGB analog color monitor with the same 
resolution, but a size of 13" (Sounds like SrcnHres and ScrnVres 
become interesting, ha?). I have seen this machine working with 
an 8086 coprocessor card: Turn on, WordStar in, it works. I've 
been told Microsoft flight simulator works too. (But, in fact, 
which IBM program is really good enough to us Macintosh 
folks?) The main interesting point on this machine was the 
presentation of RagTime on it: Its authors Mr. Brüning and Mr. 
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Everth where running a color version of RagTime. It shows an 
excellent color and b&w shading, much better as all known IBM 
EGA displays. The letters where sharp and excellently legible, 
also in 9-point sizes. In fact, the only equivalent monitor was one 
I have seen in a computer graphics studio. This was about 43,000 
— DM($12,000). Apple has done a very good Job with these 
video displays. 

Now the software: There was —as noted above— a new 
version of RagTime, which includes (in Germany) word wrap- 
ping, color display and new layout possibilities. But the main 
interesting software was 4th Dimension: A fully relational, 
programmable database which allows to create Macintosh-like 
programs [Silver Surfer]. In fact, it was a mixture between 
FileVision, Omnis 3 and Microsoft File, but it’s power is much 
more than only a combined version of these three programs. The 
example shown at the fair looks like a program explicitly written 
in a programming language, with it’s own buttons, user-defined 
windows, specialized controls and so on. The programming 
language is very near Pascal with a lot of predefined routines. It 
can create and read several files formats, including SYLK and 
ASCII text. The author searches 170 records from about 10,000 
and exports them to Excel. This action (searching, quitting and 
then starting Excel) takes about 30 seconds! It is possible to 
disable items according to the data. In the example shown, a 
complete list of French wine yards, (yes, it was graphically 
shown where the wine yards are), the author disabled the button 
“Му Cellar” if the selected Wine wasn't in his cellar, so the 
personal notes about this wine (which were in their own win- 
dows) cannot be changed. 

I think this is the biggest deal for the Macintosh since 
MacWrite. 4th Dimension overrides any other known database, 
including mainframe databases, because of its speed and pro- 
grammability. If you buy it, it comes with a complete software 
developers environment and the licenses for runtime units, so 
from the end users view everything comes from one hand, and he 
has not to buy a database program. 

Another thing new on CeBit was APD: Apple Programmi- 
erer Deuschland. This new user group is much like APDA: if, 
from Europe, you want something from APDA, their is no other 
way to get it than flying to America and buy it there. (I tried to 
get MPW here in Germany: It was impossible.) Many tools 
aren’t available here, and one intention of APD is to distribute 
these things. A developers conference is planned for April 23rd 
87 in Frankfurt/Main, and that should help local developer 
groups. This sounds very good, huh? 

OK, this was what I’ve seen in Hannover at Apple. It was 
very interesting to look at Macintoshes growing and the plans of 
Apple. A last word at IBM: they had the biggest presentation, but 
at Apple were the most people. Pagemaker on the IBM works 
very slow (on ATO3), and it needs a special monitor, Intel Above 
Memory, a hard disk and an Apple LaserWriter to work. For less 
money you can (in Germany) buy a Macintosh II with 40 
megabytes, a LaserWriter, Ragtime, some Postscript tools which 
work approximately four times as fast. The shown databases 
where slow and ugly to use, most incompatible with other 
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applications and lack the graphic data storing. Programmers 
environments are very expensive on the PC's. And last, but not 
least, the documentation for MS-DOS Computers is bad against 
IM; after reading IBM technical handbooks I think IM is a 
Roman. 

So I've found I decided the best computer one year ago: 
The Macintosh. Itshows the powerof a continuous hardware and 
software concept without critical changes in the system. 
PCMacBasic Underestimated 
Dr. Peter Markiewicz 

Columbia, MD 


Iam writing in response to the recent Basic article compar- 
ing the relative strengths and weaknesses of the compilers 
currently on the market. I think in giving the PCMacBasic 
compiler a low rating, you are missing the main advantage it has 
over the others, as well as the major purpose many people buy a 
Mac Basic compiler for, which is to modify existing programs to 
run on a new machine. 

I am not a professional programmer, and as such much of 
the work I do involves modifying public-domain scientific pro- 
grams to run on the Macintosh. / simply don't have the time to 
'start from scratch' without changing my career. Nearly all the 
Basic programs I have worked with originally started life on an 
IBMPC in BasicA, and my purpose is to 1) make these programs 
run on a Mac, and 2) improve their operation by adding features 
of the Mac environment such as windows, menus, and so on. 
Frequently, they consist of a large number of small programs 
integration, with each becoming a single menu item in a larger 
Mac program. There are usually several parameters that must be 
set for their operation, for which complex Dialog boxes are the 
natural choice. Furthermore, many of the programs share the 
same dialogs in the larger package. 

For programming of this type, the PCMacBasic compiler 
wins hands down over every other compiler in the market! I can 
say this because in a recent project to port and integrate a set of 
20 DNA sequence analysis programs, I tried every compiler 
except Softworks, and was unable to do the job until I started 
using PCMacBasic! ТЇЇ list the features it supplied which were 
essential to my project, which are supported nowhere else: 

1) Immediate operation of BasicA programs after transfer 
onto a Mac. All the programs I ported to the Mac ran with 
virtually no modification when compiled with PCMacBasic. By 
contrast, itrequired several days work to modify a single program 
of the set to compile with MS Basic, and I couldn't get it to work 
with ZBasic without totally rewriting the program, due to differ- 
ences in random access file commands. As I said, I don't have 
time to do rewrites. 

2) Rapid conversion of programs using function keys to pull- 
down menus. Once again, it was possible to rapidly convert a 
function-key driven program to one using pull-down menus. 
With the other compilers, the only alternative is to completely 
scrap the code and write menu-handling routines, which was 
impractical without rewriting the programs. 

3) PCMacBasic is the only compiler that provided acceptable 
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support for building complex dialog boxes. I was able to quickly 
define the Dialogs in the resource file, create, modify, and collect 
user input without having to rewrite the programs or use ROM 
calls. Radio buttons were managed by the Runtime, without any 
Basic coding. Several of the subprograms in the package were 
able to share the dialog without writing additional code. The 
simplicity of polling and modifying the dialogs within BASIC 
was unmatched by any of the other programs, where dialogs 
cannot be created as resources and modified in memory without 
a lot of ROM calls. 

4) Package support. The most serious problem with MS 
Basic and ZBasic to my mind is the difficulty in defining local 
variables (including strings), and integrating a setof CHAINING 
programs into a single application. It is very difficult to fuse 
several small programs into a large one with ZBasic and MS 
Basic because of this, one cannot arbitrarily define all the 
variables in a section of the program as local. The CHAIN 
command in the other systems involves unacceptable time, and 
the programs are all still separate files, just waiting for the user 
to accidentally remove a few and bomb the rest. With PCMacBa- 
sic, the PROGRAM, CHAIN, and COMMON directive allowed 
painless integration of a large set of programs into one package, 
without worrying about variable conflicts. Adding a new pro- 
gram to the package was almost like adding on a function in C. 
The individual programs became segments, which made for 
excellent memory management. As a result, it was possible to 
fuse all 20 programs into a single 200K application, and still have 
it run on a 128K Mac! The SEGMENT directive in ZBasic 
doesn't compare. Once again, to do this with the other compilers 
would have involved a complete rewrite of the code. 

5) File management and NAMEing. PCMacBasic supports 
HFS, and the FILES$ command supports opening or printing 
files from the Finder in a single line of code. One can quickly 
specify types and Creators with the NAME command. I tried this 
in ZBasic (3.02), but got occasional bombs. The PCMac form 
worked well enough, however that I could allow the user to 
specify the type of output file they wanted in a scrolling dialog! 

To summarize: 

If you don't have the time to rewrite an application from 
scratch, and want or have to use an existing BasicA program, 
PCMacBasic is byfar the best choice. I agree that it is not the best 
environment to develop anew program. Ithas serious limitations 
in areas like printer support and slow execution of compiled 
programs. However, I think that many of the Basic programmers 
out their, (including those reading MacTutor), are not profession- 
als with the time to write from scratch, want to take programs off 
the IBM to run on the Mac, and quickly add a Mac-style without 
rewrites. 

I suggest that the next time you compare compilers, you 
include a “Ease of porting existing programs” section. I think 
you will agree that PCMacBasic is by far the best in this area for 
the reasons mentioned above.[PCMacBasic has come back from 
the dead, with the authors working on a new release. We'll ask 
Dave Kelly to investigate. Ed] 
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Apple's Solder Machines Don't 
Chuck Rusch 
Eugene, OR 


Ijust finished Loy Spurlock's letter about the Mac's power 
board problems in the March '87 MacTutor, and I couldn't agree 
more. Iown an upgrade and peripherals business which is out of 
necessity getting more and more into the service and repair end 
of things. Idon'thave Loy’s electronic expertise (when we can't 
fix a board we send it to his company, Computer Quick), but I 
have done about 600 memory upgrades over the last two years 
(mostly Levco), know the inside of the Mac pretty well now, and 
would like to expand on a few of Loy's points. 

On page 5, he says that 9 out of 10 power board failures are 
in the video circuitry part of the board, and 8 of those 9 are flyback 
transformer failures, probably due to heat. I know he’s talking 
about heat in the box, and hot spots on the power board, but up 
here in the cool Northwest, while we are fixing a lot of power 
boards, I only replace a flyback occasionally. The big problem 
here is cold solder joints which he outlines in the next paragraph. 
In fact, the cold solder joint problem is so bad that I have taken 
to making a routine visual inspection of the power board with a 
6 power scope whenever I open up a Mac —regardless of whether 
there is any reported trouble with the Mac’s sweep power supply 
(Apple’s term for the board). Over the last month and a half on 
about 15 machines I have serviced which have power boards over 
two years old (most are newer), I have yet to find even one which 
was free of cold solder joints with visible cracks. That's right, 
100% of the older boards are either failing or look like they are 
about to fail. Ihave serviced probably 40 or so old power boards 
over the last six months and usually there are about six bad joints 
with visible cracks and another half dozen which look suspect. 

These bad joints occur in one of four areas on the board, and 
right where Loy says they are —where there is a large metal lead 
or pin on the other side of the board. The biggest offenders are 
the joints which hold the cable connectors. There are three cables 
connecting the power board to the rest of the computer. Near the 
top of the board is a four-pin connector which carries the sweep 
signals to the yoke of the CRT. The top pin carries a lot of current 
and controls the horizontal sweep signal. When that joint fails, 
or gets interrupted, all you get on the screen is a thin vertical line. 
On old boards, that joint almost always has a thin circular crack 
around the pin sticking through from the other side. When this 
crack gets wide enough, the current is interrupted, at first inter- 
mittently. Getting a lot of current through an intermittent joint 
apparently causes an enormous heat buildup. I have seen boards 
where part of the nylon housing for the connector to that pin was 
completely burned out, as in, gone. There is often scorching of 
the board around the pin. When it gets really bad, the heat and 
possible voltage surges begin to take out components in related 
parts of the circuitry. А sort of domino effect fans out from the 
joint, and can easily wipe out a half-dozen components or more. 
The bottom joint in that row of four is the next most likely to go 
bad and when it does, it takes out the vertical sweep on the upper 
or lower half of the picture, leaving only the other half. 
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The next two joints most likely to be cold and cracked are the 
endpins in the ten-wire connector for the power cable which goes 
to the digital /logic/ mother board. This row is horizontal, near 
the center of the board, and the joint toward the front is the first 
tocrack. Because interruptions here are interruptions to the logic 
board, symptoms include system bombs and spurious resetting. 
The third connector is the seven-wire cable carrying power to the 
CRT gun at the back of the tube. Cracks in these joints are less 
frequent, but not uncommon. I am less sure which are most likely 
to fail here, I check them all under magnification. As for 
symptoms, I remember a few machines with wavy lines on the 
screen, but cannot be certain they originated from this row of 
connections. 

The fourth are most likely to have cold cracked joints is that 
of the flyback transformer itself. These heavy metal pins form a 
circle of nine joints. There are actually two circles, one for the 
earlier smaller transformer which Loy describes as failing fre- 
quently, and a larger wider tangential circle of holes for the more 
recent robust transformer which Loy (and Apple) now use as 
replacement for the smaller one. Interesting that the holes for 
both sizes of transformers were designed into the original board 
from the beginning. 

In my experience, the above 31 joints account for most of the 
cold solder joint failures. I have found others which have been 
cracked, but not many in Loy’s other likely category —those 
connected to large foil planes in the board. 

Let me now give my version of what I think is happening to 
the power boards, why so many are failing, and what we, as end- 
users, can do about it. First let me say that what we are discussing 
here is only true for old boards, particularly those in the original 
128k machines. If you have a Mac which is at least two years old 
and has never had the power board replaced, this is your Mac. A 
quick way to check is to take the battery door off and see if it has 
a silver or black case-mounting screw. If ithas a black screw and 
the power board has never been replaced, it is an older board and 
we're probably talking about your Mac. I have found very few 
problems with the joints on the newer boards with silver mount- 
ing screws. The color of the screw obviously has nothing to do 
with the problem; it is just a quick indicator of age. Apple has 
either found a way of correcting the problem, or it hasn’t shown 
up yet in the newer boards. 

Now, as for the older boards, while it is true that some of the 
components are cheaper than they could have been and are failing 
outright as a result, it seems to me a lot of the trouble is just bad 
soldering. Why would a company as careful as Apple is about 
quality control let bad solder joints slip by? The answer is that 
there was no way they could tell they were bad. We have heard 
about the burn-in time on the bench, the torture tests, etc., that all 
Macs undergo at the factory. The early power boards also have 
a mark made with red marker, on every solder joint. That means 
that each one was visually inspected by a human being, and it 
looked good at the time. So every joint looked good and passed 
the tests before leaving the factory, but some of them, two years 
later, are cracking up and failing. Let me propose a possible 
scenario of how that could have happened. 
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The boards are soldered by passing them over a wave- 
soldering machine. The temperature of the solder can be set at 
any temperature needed, but if itis too hot, the small components 
on the board can be damaged, and if it is too cool, the large 
components will draw heat out of the joint before it sets correctly 
and a cold solder joint will result. So setting the temperature or 
boards with a wide variety of component sizes is a bit tricky. A 
cold solder joint is one which is crystalline in nature rather than 
a solid "fluid" amalgam. Normally a cold joint looks dull and a 
bit textured rather than bright and shiny, but sometimes it is hard 
to tell the difference. So some joints, particularly those with long 
metal pins or leads on the other side of the board, set up as cold 
crystalline joints and slip by the visual inspection. They also get 
by the burn-in test because there is plenty of surface contact at the 
joint initially to carry the current. I’ve been told that use of heat- 
resistant components will resolve this problem, butI have no way 
of knowing whether Apple used such components on the early 
Macs. 

But once a Mac is sold, the situation begins to change. Now 
the machine is in the user's hands and it gets turned off and on 
constantly. Everytime it is turned on, the joints heat up and 
expand; everytime it is turned off, they cool down and contract. 
A proper joint can take that expansion and contraction, but in a 
crystalline one, the crystals begin to break apart. Where? Right 
at the joint between the metal pin and the solder, hence the 
circular cracks. After two years of so, the cracks become wide 
enough so that the current is interrupted, if only momentarily. 
Result? A system bomb, a reset, the picture collapsing to a thin 
vertical line and then restoring itself, the upper or lower half of 
the picture going out, wavy lines across the screen, etc. If not 
corrected, the problems get worse; interruptions are more fre- 
quent, severe overheating and voltage surges begin to take down 
other components, the user winds up with a “smoking Mac", and 
the whole board has to be replaced. Perhaps this is why some of 
the flybacks are overheating as well. 

One customer told me that his power board went up in smoke 
just as he loaded a desk accessory called “Toaster”; at least he 
seemed to enjoy the irony, if not the expense. If caught in time, 
all that is needed is to have those bad joints resoldered at a high 
enough temperature to make a solid connection. I am now 
inspecting and resoldering up to five old boards a week, and as 
I said above, I have yet to find an old one without bad joints on 
it. 

Finally, let me add a footnote about the three double-stick 
pads which hold the plastic cover onto the power board. This 
cover is important. The power board has some pretty high 
voltages on it and can be dangerous if touched at the wrong time, 
but the cover has to be removed to inspect the joints on the board. 
Further, one of those 1"x1" pads is stuck over the four vertical 
sweep joints which I mentioned above as being among those 
likely to be bad. I usually pull the cover off, tearing each pad in 
half, although you can get by with just pulling the top one in half, 
bending back the cover to get at the board, and holding ti back 
with the side of your arm while you work on the board. I then cut 
and scrape off the part of the pad stuck to those sweep joints 
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needing inspection, being careful not to damage the board. A 
good fingernail works well here. When I am done resoldering the 
joints, a little rubber cement to both surfaces will re-glue the pads 
back together. I’ve wondered a bit whether the pad could be part 
of the reason the sweep joints are the first to go. In theory, the pad 
could insulate the joints, causing them to get hotter and expand 
even more than they would have otherwise, breaking those 
crystals down faster. Maybe, maybe not, but I trim that particular 
pad back so that it is not covering those joints, just in case. 

The point of being so detailed about all this is that if the little 
scenario I’ve outlined above is true, and the 100% figure holds 
up, we are in for a real flood of bad power boards. Your option 
is to pay a dealer about $165 to replace it, or find someone who 
knows where to look (and how to solder) to go over it for you 
before it goes bad. [You рау me now, or you pay me later"] І 
charge $35 to open the Mac, inspect the board, resolder the bad 
joints, check and reset the voltage and put it all back together. I 
charge $20, if I’m already inside the Mac for some other reason, 
like adding a fan or doing amemory upgrade. Others might want 
alittle more; I think up to $50 would still be worth it. I figure I'm 
adding to the life of the board through this service. I don’t 
recommend it unless your machine is at least two year’s old, but 
Ihave found bad joints on newer boards; there just aren'tas many 
of them and their cracks are not as big. 

Some of the above may be electronically inaccurate, I don't 
pretend to know the power board like Loy Spurlock knows it, but 
maybe there is enough truth here to help save a few more Macs. 
At least I'm not bad-mouthing the power supply itself; I'm 
fingering the cold solder joints, and who could love a cold solder 
joint? If your power board has just recently gone up in smoke, 
send it to Loy, his crew is really good at component repair, and 
at a fraction of the normal cost of replacing it. 


TextEdit and MS Basic 3.0 
Blake Miller 
Birmingham, AL 


Ihave been keeping up with your articles for some time now. 
I have every issue of the magazine. I am letting you know, so you 
do not think I just came out of the backwoods of Alabama.... 

After reading your recent article on BASIC in the March 1987 
issue of MacTutor, I have noticed that these strange and arcane 
words were also highlighted with my version of MS BASIC 3.0 
BINARY as well. “Spurred on by the curiosity of one so 
entranced with things not oft told the common man for fear he 
were to cause some inadvertent harm", I rushed for my copy of 
Macintosh Revealed, turned to the section on TE Edit and 
immediately began to type in the rest of the TE commands which 
are in the ROM. Perhaps you did the same? 

The enclosed page of paper displays my results. Other 
commands are highlighted too. I have indicated what I would 
believe to be the correct syntax for using these with MS BASIC. 
This is based upon what MS used for their example on the disk. 
That is, 

* A Handle is returned by WINDOW(6) 
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* The address of the text is returned by SADD(Text$) 
• Тһе Length is returned by LEN(Text$) 
е А rectis given by VARPTR(Rect(0)) 


I have tried TEScroll with varied results. This command 
does indeed scroll the text. It will move it anywhere you want 
within the Edit Field. However, it, as well as TECalText, 
TESetText, and TEUpdate, do not wrap the darn text! 

According to Macintosh Revealed V2, on page 244, it says 
that "TECalText wraps a edit record's text to its destination 
rectangle, calculating its line starts and nlines." Fine and dandy. 
I should expect so much from MS BASIC with a command that 
is not “official”. However, they use TESetText in their example 
on the disk. This is the program which reads the text files. In 
Macintosh Revealed V2 on page 242 and 243, it also states that 
"TESetText sets the text to be edited by an edit record." And that 
“TESetTex automatically wraps the new text to the destination 
rectangle, calculating its line starts and nlines.” With “The new 
text is not automatically displayed on the screen; call TEUpdate 
to display it." 

When you examine what TEUpdate is supposed to do, you 
will find that Macintosh Revealed again says that ““TEUpdate 
draws an edit record's text in its graphics port. .....updRect is a 
rectangle in the local coordinates of the record's port (usually a 
window). The text to be drawn will be clipped to the intersection 
of the rectangle with the record's view rectangle." And again 
“The record's text is automatically rewrapped to its destination 
rectangle before drawing; there's no need to call TECalText 
first." 

Well, I tried another text file with the example program that 
MS sent on the disk. Unless you have saved your original word 
processing file to have a carriage return after every line, your text 
will gooff into the weeds off the right edge of your window or edit 
field. THERE IS NO WRAPPING OF TEXT! I have written 
small sample programs trying all manner of these calls and 
parameters with the Edit Field statement and all. Ican not getany 
text tO wrap. 

I made the edit field contents scroll with TEScroll, and if I 
went far enough around, I could see all my text way out there at 
the end of the line, but there was not wrapping into the “destina- 
tion rectangle”. It seems that somehow, the wires have been 
crossed between the ROM and what MS BASIC does in an Edit 
Field with an edit record. 

I will try to write a line editor using the TEScroll and some of 
the things I have talked about here. If I can, I will send you guys 
acopy. In the meantime, if you learn anything about how the TE 
functions can be used to wrap text, please let us all out here know 
soon (via MacTutor, of course). This will be greatly appreciated. 

[Text is drawn with TEUdate, which uses the line starts array 
(TECalText) to wrap the text to the destination rectangle. If your 
destination rectangle is larger than your view rectangle, typically 
your screen, then the text appears not to wrap. In order to get it 
to wrap where youcan see it, the destination rectangle must be the 
same size or smaller than the view rectangle. Your problem is that 
MS Basic is changing the destination rectangle so it can accom- 
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modate long program lines. TextEdit is wrapping the lines, but 
not to the rectangle you think. -Ed] 
TESETTEXT SADDCNotes$), LENCNotes$), WINDOWCO) 
TECALTEXT WINDOWCO) 
TEUPDATE VARPTRCRECT(O)), WINDOWCO) 
TESCROLL HorizPixInt, VertPixInt, WINDOWCO) 
TESETSELECT CharPosStart, CharPosEnd, WINDOWC(6) 
ТЕАСТІУАТЕ WINDOWCO) 
TEDEACTIVATE WINDOWCO) 
TEKEY SADD(har$)* 1, WINDOWCO) 
TEDELETE WINDOW(C6O) 
TEINSERT 
SADD( InserText$), LENCInsertText$2, WINDOWCO) 
$10,000 PhotoTypesetter... 
W. McBride 
Clamart, France 


I wish to answer a question from your Mac World Expo Resort 

which was published in the March MacTutor: 
question: $10,000 Phototypesetter? 
answer: Yes 

That bit was easy but now lets get down to business. Let me 
give youa few figures first to wet our appetites. The 70,000 Macs 
here in France include all types. Apple France now has reduced 
its authorized Mac dealers to 300, not counting the VAR’s. The 
MacPlus now costs 19,900 francs ($3,350). Here’s the one 
you’ve been waiting for. About ten months ago, the Allied 
Linotype L-100 was reduced in France from 440,000 francs 
($74,576) to 330,000 francs ($55,932). If follows that you don’t 
find such a beast down at your local friendly copy shop, but I 
didn’t just want to talk to you about Linotype politics. I note with 
much interest that the postscript RIP is available from Adobe and 
I would not be at all surprised if you have already found a marking 
engine at the required resolution. In case it wasn’t already clear, 
I wish to be involved in your project to design, construct and 
market a phototypesetter which is within the grasp of at least a 
part of the Macintosh community. Your $10,000 figure is very 
significant. When the Apple LaserWriter was introduced, it cost 
just that amount, whereas today it is down to $8,400. if your 
project includes from the outset a realistic approach to the 
European market-place, I’m sure it would really go places. The 
management of its development and marketing is critical and the 
time is right. (Unfortunately, the project is stalled for lack of a 
suitable phototypesetting engine mechanism. It seems all the 
phototypesetters are custom engineered by the same companies 
trying to rip us off. No one has an OEM engine. Compu-Graphic 
has a new offering in the postscript desktop market: $100,000 for 
the whole system. Vari-Typer has a new 600 dot per inch 
LaserWriter: $18,000. Meanwhile, Allied remains the only 
postscript phototypesetter: $50,000. -Ed] 

Loves MacTutor 
Glenn McPherson 
Rockville, MD 


I have been purchasing MacTutor off the newsstand since 
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1984. Now that I have the time to seriously develop software for 
the Mac, I am subscribing to your fine magazine. Each month I 
get Dr. Dobb's, Computer Language, PC Tech Journal, and 
BYTE as well as many other non-technical magazines. MacTu- 
tor is one of the best (the BEST for the Mac) journals that I read. 
Keep up the good work! 
Basic Compiler vs Interpreter 

Steven C. Leach 

Santa Clara, CA 

I would like to put in my two cents worth about the new 
Microsoft Compiler (V1). Yes it does create big code, and it is 
certainly not the fastest compiler around but the combination of 
interpreter compiler environment is one I find very hard to beat. 
Ibought Lightspeed C as soon as it was available, I even paid list 
price out of my own pocket, and I am not a developer. Whenever 
I can get away with it, I use the MS Basic with all of the CLR 
libraries I need. 

The main reason for my writing this letter is to let others know 
some of the quirks of the MS compiler (V 1) versus the Interpreter 
(V3). Most of these quirks show up when your source starts 
getting above 64K (that’s only an estimate; I have not looked into 
the compiler with MacNosy nor do I want to). 

1) The interpreter gladly allows the programmer to DIM an 
array by simply declaring the array and using it in a piece of 
program, providing the index never goes above ten there is no 
problem. 

The compiled program will do likewise until a certain pro- 
gram size is reached then it starts giving the user arun time error 
number 38, which is of course, not documented. So if you get run 
time error 38 start looking for an undimensioned array. 

2) The interpreter doesn’t care if you use multiple statements 
on a line, providing you don’t exceed a line length of 255 
characters. 

The complied program will actually cause a system error 
ID=02 when the subroutine levels get more than 3 and the 
program size exceeds the 64K level. In the documentation it says 
that multiple statements on a line are no longer necessary, but of 
course does not mention this problem. 

3) The interpreter will happily perform a CLOSE #1 even if 
file #1 has been closed before this statement is executed. 

The compiled program of course chokes on this occurrence 
and causes an ID=02 system error. Admittedly this situation is 
rare, as a matter of fact, I found this quirk only by mistake (my 
mistake). 

4) Last, but not least by a long shot, is that the compiled 
programs seem to be unable to read the serial port with any 
accuracy or consistency what so ever. I haven’t figured this 
problem out so if any one can help I would be very grateful. [It's 
a bug and there is a patch fix to the compiler. -Ed] 

These situations occurred on several different programs, the 
source text file for the interpreter ran between 70-120K and of 
course the compiled programs ran well over the 100K mark. Oh 
well it’s a great way to debug programs that have to be done 
inside a month or two. 

Thank you for providing this forum. Have you thought about 
Genie or CompuServe as an online service so we can make local 
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calls and upload, download all your great stuff? One last request, 
could someone please write an article on how to give an applica- 
tion from one of the basic compiler an icon, and of course how to 
give an icon to the files produced from that application? 
MS Basic Suggestions 
G.M. Greytak 
Long Beach, CA 

Double Daves: Keep up the good work. It is to your credit 
that Microsoft relies on your judgement. 

You asked for suggestions for improvements to BASIC. I 
have a few which may not occur to most users. I use BASIC in 
an interpretative mode to write ad-hoc simulations relative to 
Civil Engineering and business problems I am studying. Loop- 
ing through a range of parameters helps me determine the 
sensitivity of a design to them. Graphing the results gives me 
reassurance that the algorithm is the proper one. The questions 
I consider do not lend themselves to applications. CivilSoft, 
Excel, etc. impose constraints which limit what I wish to explore. 

* It would be nice to use the Greek alphabet for variable 
names as single characters, У, not SIGMA. 

* Working in radians is unnatural. Wouldn't it be nice to 
declare degrees instead of writing and calling a function. 

е So would being able to re-define the origin of the screen 
say x=256, y=171 or 0,342 instead of the present 0,0 at 
upper left. 

е MacDraw can plot Multi-pages, wouldn't it be nice to plot 
to several windows (virtual screens) (Do you recall the 
stripchart mode in Appleplot?) 

* How about multi-line function declarations? 

Or MAT(matrix) commands/operations? 

* I believe that there are SANE functions which are not 
usually implemented, i.e. Present value(parameter list 
including i,n). Using something of this nature is more 
user friendly than digging up the math handbook for the 
formula. 

* I don’t believe CLR libraries contains some of the 
interesting possibilities, eg: the area under the normal 
curve to a given z value. 

* In any case the incorporation of some of the libraries 
makes the wish for all of them to be available in the 
language itself. 

In other words, I want BASIC to be a smart computation 
pad. [I agree! Itisa great frustration of mine that no one yet knows 
how to write a suitable Basic for the Mac. Maybe we could 
license HP's 9836 Basic? -Ed] 

New Word for the Mac 

Sarah Chart 

Microsoft Corp. 

A new release of Microsoft Word 3.01 is scheduled to be 
released in June that will work with the Mac II and fix all 
known problems in version 3.0 (see mousehole column). This 
update will be sent at no charge to all registered users of 
version 3.0. A special thank you goes out to all individuals 
who took the time to contact Microsoft with problems found 
in version 3.0. 
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Changes to the New Pagemaker 2.0 


Aldus has released version 2.0 of it's Pagemaker publishing 
program and it has become apparent that this new version differs 
in many ways from the previous 1.2 version. Most of the new 
features have been widely mentioned in the trade press previ- 
ously. These include a new approach to text edit that is substan- 
tially superior to the previous method. Under version 1.2, which 
was written in Lisa Pascal, the resource manager was heavily 
used to keep track of various parts of a document, including text 
blocks. This apparent "over use" of the resource manager was 
responsible for several new System File versions as Apple 
attempted to fix the multitude of bugs in the resource manager 
that Aldus kept finding with their Pagemaker product. As is well 
known, the text editing of Pagemaker never did become bug free 
in 1.2 and the decision was made to rip it out completely and build 
anew textedit not based on resources. Version 2.0 was re-written 
from scratch in C, and so is really an entirely new product, rather 
than an upgrade. The obvious limitations have been fixed; the 
text editing is very robust now, you can have up to 127 pages, and 
postscript placement is now supported. Multiple pages can be 
added or deleted. Kearning is supported automatically. What is 
less well known, is how this version differs from 1.2. Figure 1 
illustrates some of the differences and suggests that version 2.0 
is not completely compatible with how things were done in 1.2. 
If you are attempting to carry on as usual from version 1. 2, you 
may be surprised at some of the differences. 


Auto Leading Calculation Changes 


The most significant difference is that the auto leading calcu- 
lation in 2.0 has been changed. Under version 1.2, Pagemaker 
matched very closely the way MacWrite dealt with text. If you 
place some text in MacWrite and Pagemaker 1.2, you'll find that 
the leading is nearly identical. We use times 10 pt for our text, and 
a mono-spaced thin saratoga Әрі. font for our source code listings 
in this Journal. Leading calculations for both MacWrite and 
Pagemaker 1.2 suggest that the leading is picked up from the 
screen version of the font and that this is not uniform for different 
fonts. However, the font differences work to the readers advan- 
tage. The leading for both MacWrite and 1.2 appear to produce 
a 12 point leading for times 10 pt fonts and a 9 point leading for 
the saratoga 9 pt font. This results in a very readable text with a 
tightly spaced source listing, just what you would want. 

In version 2.0, the leading calculation has been changed so that 
itisuniform for different fonts. The leading is calculated as 12096 
of the font size rounded down to the nearest half point. Times 10 
pt gets a 12 point leading, very similar to MacWrite and version 
1.2. However, the saratoga 9 pt font gets a 10.5 pt leading, which 
is very airy. The June issue of MacTutor used this default leading 
in version 2.0 entirely and you can see the obvious wasted space 
in the source code listings. About seven pages of editorial was 
lost over the entire Journal due to this airy spacing of the saratoga 
font. To re-create the same effect as version 1.2, requires re- 
leading all the source code in the saratoga font to a 9 pt. leading, 
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Fig. 1 Pagemaker 2.0 Changes 


a very time consuming task. 

Aldus has provided a patch so that the auto leading calculation 
can be changed with FEdit. The patch is given at the end of this 
discussion. We have tried patching the auto leading calculation 
to provide 110% leading. This results in tighter leading for the 
times 10 pt font, which makes it harder to read, and a tighter 
leading for the saratoga font, which takes some of the air out of 
it. However, the leading for the saratoga font is still not as tight 
as it was under version 1.2. We also tried using the 110% leading 
with a manual re-leading of the saratoga font listings to 9pt. This 
gives slightly tighter spacing than version 1.2 because the times 
10 pt font is spaced tighter. Given the fact that the saratoga font 
must be re-leaded anyway to get the same effect as version 1.2, 
we are undecided as to whether the times 10 pt font would best 
be left at 120% leading or changed to 110% leading by using the 
Aldus patch. Such are the considerations you will need to go 
through in trying to decide if you want to patch your copy of 
Pagemaker to change the auto leading calculation. A future 
version will have this choice placed in a dialog box. 


Tabs Changed 


Another thing we have noticed is that MacWrite tabs are not 
being picked up the same way in version 2.0 as they were in 
version 1.2. We took a source code listing and set the tabs in 
MacWrite then placed it in version 1.2. The listing lined up 
correctly in a manner very similar to the MacWrite file. However 
when the same listing was placed in version 2.0, the comments 
in the source code did not line up suggesting that the tab spacing 
was changed. We had to manually re-tab the listing to get the 
comments lined up again. So there is something different about 
how version 2.0 picks up tabs from MacWrite compared to how 
version 1.2 worked. 


indentation of MacWrite and Word Files 
Version 2.0 now respects the left margin setting of MacWrite 


files as we reported last month. This has the effect of indenting 
the text placement in Pagemaker, which, if you want the text to 
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flow into the columns, leaves you with a useless column of text 
one inch wide as shown in figure 1. There does not appear to be 
any way to simply force Pagemker to re-flow the text into the 
Pagemaker columns regardless of the left margin setting in 
MacWrite. The only fix for this is to re-set all of your MacWrite 
rulers to move the left margin to the one inch mark. Microsoft 
Word files also seem to default to an indendation on the right 
when placed formatted in Pagemaker. However, this is easier to 
fix. Check the right indentation option in Microsoft Word, and set 
it to zero. Then the document will place correctly in Pagemaker. 
Aldus considers this a feature that both Write and Word files get 
indented according to the margin and option settings of the 
programs. We think Pagemaker is too particular and that more 
flexibility should be allowed the user in directing Pagemaker to 
re-flow text into Pagemaker columns regardless of margin and 
option settings. Another candidate for a configuration dialog 
directing how Pagemaker will work. 

Another hidden gotcha is that Word files saved as MacWrite 
format from Word 3.0 cannot be placed in Pagemaker. The 
program either puts up a dialog box that says the file contains 
fonts not in the system file and refuses to place the remainder of 
the document, or else simply refuses to place any portion of the 
document. This is also true of any file created from a file saved 
from Word as a MacWrite file. Even if you open the file in 
MacWrite and save it again, you can have problems getting all of 
the file placed. The most effective fix is to copy the text into the 
clipboard and paste it into anew MacWrite file, and then place it 
in Pagemaker as a text only file. 


Paint Files Display Bug 


When MacPaint type files are reduced and displayed at actual 
size, the background pattern becomes a giant checkboard pattern 
as shown in figure 1. Apparently this is a bug. Also, the manner 
in which paint type files are displayed when viewing the entire 
screen has been changed. The paint file is not recognizable except 
at actual size. Under version 1.2, the display of paint files is 
clearly superior. Under some circumstances draw files are dis- 
played on the screen with gaps in the text. This bug is related to 
the line length of the text and doesn't seem to be easy to re- 
produce. 


Missing Features 


There are a number of features that were expected to be in this 
version, which have been postponed to the next version. One 
thing is an expanded configuration dialog that would allow the 
user to set the auto leading percentage, and turn off the indenting 
of MacWrite files so that text can be re-flowed into the column 
settings of Pagemaker with formatting intact without regard to 
the margin settings. 

Now that the new system file supports nested menus, we would 
like to see the type menu re-done. It takes too long to change the 
font and size in Pagemaker because of the clumsy use of a dialog 
box. The font, size, style and leading could be set-up with nested 
menus like Scoop (Target Software's new publishing program) 
uses. This would greatly speed up the process of making text 
changes and would allow a greater selection of style and leading 
options. 

Automatic placement of text without having to click at the 
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bottom of one column and then place at the top of the next column 
is another feature that did not make it into this version. Other 
features would be a clone function like FileMaker that would 
copy the settings and master pages to a blank document. The 
ability to copy the left master page to the right master page to 
speed up the creation of master pages is another helpful feature 
needed. And finally, one thing that is really needed is the ability 
to open more than one document at a time and merge Pagemaker 
files together. Now that Pagemaker can handle 127 pages, many 
little 16 page files could be concatenated to take advantage of the 
larger document size, but Aldus did not make provision for 
merging documents together. In conclusion, version 2.0 really 
represents a migration to C for Aldus, and a correction of the 
obvious deficiences. We look to the next version to provide the 
new features missing from version 2.0. 


Aldus Auto Leading Patch 


Using FEDit or a similar file editing tool, open a copy of 
PageMaker 2.0 and search for the HEX string: 


JF3C 000A 3F3C 000С IFØ 4EAD 


This string should be found only in one place in PageMaker 
2.0: at the end of sector 3A7 and the beginning of sector 3A8. The 
000A is the last word in sector 3A7. The 000C is the second word 
in sector 3A8 and these are the two words that can be changed to 
change the autoleading calculation. The autoleading value is a 
fraction: the numerator is the 000C (212 decimal) and the 
denominator is the 000A (210 decimal), hence the standard 
autoleading is 12/10 or 120%. Either or both numbers can be 
changed to virtually any fraction desired. 

Examples: 

11096 leading: use 11/10. Change 000C to 000B 

105% leading: use 21/20. Change 000C to 0015 and change 
000A to 0014. Change the value in the corresponding sector and 
write the sector back to disk to make the change permanent. 


Straight Story on 32K Limits 
Joel West 
Contributing Editor 


Several letters in the June 1987 MacTutor ask about 32K 
limits. I'll try to clear up some confusion on this topic. 

There is nothing in the Mac or 68000 that REQUIRES a 32K 
limit, only shortcuts that make for more compact code if you 
assume a 32K limit, so if you object to such a limit, let your 
compiler vendor know. Certainly any compiler could have a ‘no 
limit' compiler toggle to generate code without such limits. [And 
we can't understand why all compiler makers do not add such a 
configuration switch. -Ed.] 

When you talk about a “32K limit", there are at least four 
separate limits. I'll illustrate my answers using references to 
MPW, since that's Apple's official system and also the one with 
which I'm most familiar, but the general principles apply to all 
Mac development systems. 
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Two 32K limits relate to code references (segments): 
1. The size of a segment. 


The 64K ROM resource manager had a bug that it sometimes 
barfed for resources longer than 32K. This was fixed in the Mac 
Plus, and the later Segment Loaders handle longer segments just 
fine, so this is a moot issue (except for obsolete machines.) To 
quote from the MPW Reference Manual description of the Link 
command (MPW 1.0, APDA draft, p. 310): 


Link -ss size 
"Change the maximum segment size to size. The default value 
is 32760 (32K less a few overhead bytes). The value size can be 
any value greater than 32760. 64K ROM note: Caution! Appli- 
cations with segments greater than 32K in size may not load 
correctly on Macintosh with 64K ROMs." 


The jump table only has a 16-bit offset (within a segment) for 
each entry point. I haven't tried long segments, so I can't say 
whether it also plays tricks with the jump table to place dummy 
entry points within the first 33K —this would only be for routines 
called from other segments. Of course, if you only have one 
segment, the jump table is irrelevant, as long as the main entry 
point is within the first 32K. 


2. Addressing within a segment. 


À routine does a JSR to another routine in the same segment. 
The most common way is to use "Program Counter with (16-bit) 
Displacement" (opcode $4EBA); a 16-bit signed displacement 
follows the JSR opcode word This is default for MPW Pascal, C 
and most other compilers, and the source of the 32K limit 
problem. 

To get around this, if you have a segment » 32K, MPW 1.0 
requires that you put your programs into the segment in such an 
order that no inter-routine references are more than 32K apart. 

On the 68020 you can use a subset of “PC Indirect with Index 
(base displacement)" for a 32-bit displacement. This is very 
wasteful to use by default if most programs have segments « 32K. 
However, compiler makers should provide the option of using an 
instruction that does not limit the branch to 32K if the user wants 
it, regardless of the overhead. 


Two relate to data: 


3. The size of global data 


Global data referenced to A5 has a limit in MPW (1.0 and 
2.0b1), which allows only 32K of for ALL static data, such as 
variables allocated at the outermost scope, string constants, etc. 
This is a severe limitation for moving mainframe programs, 
hopefully one to be fixed in the future. 


4.  Thelargest indexable size of an array 
Arrays do not have to have a limit. This is a decision made by 
a compiler, and the easiest of the four to handle properly. 


For example, MPW Pascal 2.0b1 allows you to declare large 
arrays (since Pascal requires fixed-size array declarations) and 
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indexes such arrays slightly differently (sign-extending the index 
to a 32-bit long). Like any C compiler intended to compile 
programs designed for UNIX systems, MPW C assumes any 
array can be longer than 32K. 

Because the last point is important and often misunderstood, 
I've enclosed some sample programs to demonstrate the point. 
The code generated for arrays of byte-sized elements would be 
somewhat different, since the index can be used directly, but the 
principle is the same. 


The Pascal program 


PROGRAM Arrays; 
($R-) (Small, clean code) 
TYPE 
HugeArray = ARRAY(1..200090) OF LONGINT; 
VAR 


SnallArray: ARRAY [1.. 1001 ОҒ LONGINT; (400 bytes) 
BigArray: “HugeArray; ( 80,000 bytes ) 
i: INTEGER; 

GIN 


FOR i := 1 TO 100 DO 
Smal lArray[i] := BigArragy^[i]; 
END. 


is compiled by MPW Pascal 2.0b1 to (edited DumpObj output): 


MOVE.W #1, $FE6ACA5) 
BRA.S there 
again: 
MOVE.W $ҒЕбАСА5),00 ; 16-bit array index 
ASL.W 82/00 ; 16-bit array displacement 
MOVEA.L $FE6CCA5), Ad 
MOVE.W $FE6ACA5),D1 ; 16-bit array index 
EXT.L 01 ; 32-bit array index 
ASL.L 82/01 ; 32-bit array displacement 
LEA $FE6CCA5),A1 ; dereference pointer to array 
MOVE.L $FCCA0,D1.L2, $00CA 1,D0. W) 
pnote 32-bit, 16-bit displacements 
ADDQ.W #1, $FE6ACA5) 
there: 
CMPI.W #180, $ҒЕбАСА5) 
BLE.S again 


The C program 


typedef long НодеАггау (200001; 
long SmallArrayl[ 100]; 
HugeArray *BigArray; 
short i; 
/* a register short in main() would be cleaner, 
but not exactly the same as Pascal example */ 
mainc) 
( for Сі=0; i« 100; i++) 
SnallArraylil] = C*BigArrag2[Li 1; 


is compiled by MPW C 2.0b2 to: 


CLR.W i(A5D 
again: 
MOVE.W iCA52,D0 
EXT.L 00 
ASL.L 82/00 
LEA SmallArrayCA5), Ad 
MOVEA.L BigArrayCA5),Al 
MOVE.W iCA5),D1 
EXT.L 01 
ASL.L #2,D1 
MOVE.L CA1,D1.L2, CA0,D0.L) 
; Note both are 32-bit displacements 
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ADDQ.W #1, 1СА5) 
СМРІ.М 8100, 1СА5) 
BLT again 


[Note: neither Lightspeed Pascal nor Lightspeed C will allow 
arrays over 32K. Obvously the future of the Macintosh II in the 
workstation market will be seriously limited by these restrictions 
of the softare development tools to support large compilations 
and data structures. We suggest that Apple and third party 
developers had better start taking steps to address these issues if 
the Macintosh II is to become a force in the workstation market. 
-Ed] 


System 4.1 Compatibility 

Apple has released the new “Universal” system file, version 
4.1, along with Finder 5.5. This software is now shipping with the 
SE and Macintosh II and is Apple's first attempt at creating a 
system that will bring together the Mac Plus, SE and Mac II with 
the same capabilities in as far as that is possible. As a result of the 
new software, we are beginning to get reports of what works and 
what doesn't with the new system software. If you have addi- 
tional reports, please communicate them in a letter to the Editor 
sO we can continue to report on potential problems. 

MacTerminal 2.0 Patch 

Programs that were compiled using a low memory global 
called BasicGlob, no longer work with the new system. This 
includes MacTerminal, and programs created by the MegaMax 
C compiler. It seems this low memory global was assigned to 
Apple's notorious MacBasic which never got past Microsoft's 
eagleeye. It wasoriginally usedas a holder fora pointer to Basic's 
global variables so that Desk Accessories could have their own 
global variables. At least this is the use MegaMax made of it. 
This location has now been reclaimed for use with nested menus 
in the new system file, causing MacTerminal to crash eventually 
or upon exit to the Finder. The fix is to patch all references to 
BasicGlob to AppleScratch, a legitimate “spare part" for appli- 
cations. Search for all instances (there are 4) of the hex low 
memory global 02B6 and change it to 0A78. This will allow 
MacTerminal to operate with system 4.1. 

MegaMax C Patch 

For any application built with the Megamax C compiler, patch 
your application as follows: 

Find 2878 02B6 and change to 2878 0A80, 

then find 21CC 02B6 and change to 21CC 0A80. 

This is the same BasicGlob problem as MacTerminal, but uses 
adifferent scratch location. Contact MegaMax at (214) 987-4931 
for a compiler upgrade if you are developing C programs. 
MegaMax also has a little utility program that makes this patch 
for you, which we will publish next month. 

Ask Apple Tech Support 

Chris Derossi, MacTutor contributing editor and former Edi- 
torial Board Member, will begin authoring an Ask Apple Tech 
Support column for MacTutor on programming questions for the 
Macintosh family. Chris is currently employed by Apple in it's 
tech support department. This new column will be an "official" 
Apple column that will give the "official" Apple answers to 
toolbox, programming and system software questions. We are 
asking our readers to help the column get started by sending your 
"Ask Apple" questions to MacTutor, where they will be for- 
warded to Chris for use in his new column. Questions should be 
of a technical nature involving programming issues, preferably 
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related to the Mac ROMS or system software. Save the fluff 
questions for MacUser. 
Think Changes Offices 

We have had reports that the phone number to Think Technolo- 
gies is no longer in service and there is no new number. This has 
sent a chilling ripple among developers that perhaps Think, 
makers of the popular Lightspeed C and Pascal compilers, was 
doing out of business. We are delighted to report that this is not 
the case, that only the phones have been changed. The new 
number is 617-275-4800. New versions of Lightspeed C and 
Pascal are being prepared to support the new Inside Macintosh 
Volume 5 traps and equates. 

LightSpeed C & Pascal for the Mac Il 
Philip Borenstein 
THINK Technologies 

Lightspeed Pascal is being updated to run on the Mac II and 
other 68020 machines as well as support the new traps and 
equates for the SE and Mac II machines. A major release of the 
Pascal compiler with new debugging features and full 68020 
support is nearing completion for release this summer. In the 
meantime, developers who have a Mac II or are expecting their 
Mac II’s shortly, can call Think and receive a beta copy of 
Lightspeed Pascal 1.01. This version will run on the Mac II as 
well as on other 68020 Macs. It has been available to all 
registered Lightspeed Pascal users who ask for it since December 
1986. A general upgrade will be available shortly. 

Users who want to use 256K ROM stack-based traps right 
away can take advantage of Lightspeed Pascal’s inline feature. 
For example, if there is a trap Foo that returns an OSErr and takes 
two arguments, an integer anda Ptr, and its trap number is $A000, 
you woud write: 

function Foo Ci: integer; p:Ptr2:OSErr; 

inline $4000; 

Lightspeed C owners can use the current version (2.01) on the 
Mac II. Togettothe256K ROM traps, they would need to declare 
the following: 

pascal OSErr Foo С) = 0xA000; 

The C programmer is responsible for making sure that the 
arguments passed are the right size. The pascal directive ensures 
Pascal stack discipline. 

The best way to use these features is to create a source file of 
256K ROM trap routines and then add the file to your project. 
When Think releases the 256K ROM libraries, you can remove 
your file and add the library. Think is committed to providing the 
best development environment for the Macintosh and the best 
possible support for our customers. If there is anything I can help 
with, please let me know. 

Copy To Mac SE Bug Fix 
John Foster 
Adjuvant Instruments 
Alameda, Ca 

The new 6.5 version of Copy To Mac includes a patch file that 
fixes some bugs in the new Platinum Mac Plus and SE ROMS. 
This bug causes the wrong tag information to be written to the 
disk, which makes undeleting files unreliable. The file, named 
CPS Tag Fix, also corrects another bug in the SE ROM that is 
causing the upper drive in the Mac SE to turn on and off 
unnecessarily. To use CPS Tag Fix, copy the file into the system 
folder of a hard disk or a startup disk. On the welcome to Mac 
screen, you get a note that the fix has been installed. These tags 
are a feature of the Mac that provides for more reliable recovery 
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of deleted files and some damaged disks, but Apple has several 
times in the past changed their minds about supporting file tags. 
Asaresult of the SE bug, official support of file tags is currently 
"out of favor". The following information is taken from a 
technical note supplied by Central Point Software with their new 
Copy To Mac version 6.5. [We think Apple needs to begin giving 
much more attention to making the file system more robust and 
recoverable from the disk crashes that plague us all. -Ed] 
File Tags 

All files are made up of 512K byte blocks on a volume. A tag 
is associated with each block on the disk describing which part 
of which file this block belongs to. The MacTools undelete files 
option reads the tag information from each block to help recover 
undeleted files. Tags written by a 512K un-enhanced Mac are 
correct. Tags written by a Mac 512КЕ or Mac Plus with 128K 
ROMS or a Mac SE are unreliable. This has prevented the 
MacTools and other recovery programs which rely on tags from 
working correctly. What makes the disk tags unreliable is a 
feature called the track cache found in the SE ROMS and newer 
Platinum 128K ROMS. The track cache, (see tech note 81) is 
different from the RAM cache found in the control panel. 
Whenever the Mac needs to read or write one or more blocks, on 
a 3.5 inch disk, the disk routines must first step the drive's read 
/ write head to the appropriate disk track and wait for the desired 
blocks on the track of the spinning disk to pass by the head. While 
itis waiting, other blocks on the track might pass by the disk head 
first; blocks which are not needed now, but might be requested 
later. In most cases the Mac has nothing else to do while waiting 
for the desired blocks so it reads the other blocks passing by into 
an area of RAM called the track cache. If an Application needs 
to read the other blocks, the disk routines will simply provide the 
blocks from the fast ram track cache rather than re-read them 
from disk. This generally improves disk access speed and effi- 
ciency. The track cache can store blocks from just one track at a 
time. Track caching can occour while the disk routines are 
waiting to read or write to a track. Here is how the track cache 
disturbes the file tags. 

When a file is written to disk, the Mac file manager, places the 
tag values to be written into a special global tag location for use 
by the disk routines. The disk routines are designed to take the 
value stored at this global location and write them as the tags with 
each block. If while waiting for the desired blocks to pass by the 
read / write head, one or more other blocks pass by first, then the 
disk routines will read these blocks into the track cache. Unfor- 
tunatley, when a block is read into the cache, that block's tag is 
also read into the same global tag location, overriding the 
previously correct tag values left by the file manager. When the 
desired block does pass by, the tags written to disk will be from 
this other block read previously rather than from the correct block 
now being written. Tags written to the disk may be wrong 
whenever the disk routines have an opportunity to cache a block 
BEFORE writing a block. CPS Tag Fix corrects this problem 
without affecting tag caching. When CPS Tag Fix is installed at 
system start-up, the tag values are written to a safe memory 
location allowing the tag values to be restored when the desired 
block passes by the read / write head. Unfortunately, tags are not 
supported on most hard disks. See tech note 94 and page two of 
tech note 96. To fix tags on existing disks, make sure CPS Tag Fix 
has been installed then copy all the files onto new inited disks 
from the Finder desktop. The copies made will then have the 
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correct tags. 
SE Upper Drive Bug 

CPS Tag Fix also corrects the SE internal drive. Without the 
fix, the upper dirveruns slowerand noisy. Try re-starting the Mac 
with a disk in the upper drive and you'll see the difference. The 
upper drive makes twice as many noises in disk operations. The 
source of this problem lies in an SE routine in the ROM called 
JDISKSEL. This routine selects the desired drive. Sometimes 
this routine is called even though the proper drive is selected and 
spinning. But that is not a problem. However, the routine itself 
first assumes that the lower drive should be selected and actaully 
selects it! It then checks if the assumption was right, and if the 
upper driver should instead be selected, it then correctly selects 
that! Butif the upper drive was already selected and spinning, this 
momentary de-select results in turning the upper drive motor off. 
Another part of the disk code, quickly notices the motor is now 
off and turns it back on again. This rapid motor on/off makes the 
additional noise similar to stepping the read write head from one 
track to the next. The disk code must wait another brief moment 
to make sure the disk is back up to speed before continuing. 
During normal disk operations, The JDISKSEL routine is called 
quite frequently, turning the upper drive off and on every time. 
The CPS Tag Fix file patches JDISKSEL so the upper drive is not 
deselected / reselected. Apple might provide their own fix to the 
SE upper drive ina future release of system software. [Is it in 4.1? 
We don't think so. -Ed] CPS Tag Fix is designed to respect other 
system patches if it finds another patch already installed, it does 
not install it's own patch so as not to produce a conflict. Contact 
Central Point Software at 503-244-5782 and request the Copy To 
Mac version 6.5. 

Mousehole Remarks 
Tom Pittman 
Manhattan, KS 


The May 1987 issue of MacTutor contained several remarks 
by correspondents that can be answered better than they were: 
Anthony Oresteen wants to generate text files where no line is 
greater than 68 characters. It's not really hard to do on the Mac. 
The most obvious is, as he suggsted, to compose in MacWrite and 
Save as text with carriage returns at line ends. Manually getting 
rid of blank lines between paragraphs is much less work than 
manually cutting each line. But even that is unnecessary. I 
believe the text editor QUED can be programmed to delete blank 
lines. If not, the editor MEDIT (version 1.3 is free, version 1.5 is 
$25 shareware from most BBS systems) certainly can. But why 
use two programs at all? I do exactly the same thing all the time 
in MEDIT: I just set the window width to the desired line length, 
using the mon-spaced Monaco font, then run a macro to cut all 
folder lines. A few seconds and the file is converted. The same 
macro also coverts curly quotes to the IBMish straight ones. 
"Misteray" in the Mousehole report notes the existence of Fax 
add-on boards for the PC and speculates that the Mac II will allow 
these kinds of things on the Mac. All that is needed is a fax- 
compatible modem, which could be plugged into the serial port 
of any Mac. The CPU that does the data compression in the add- 
on boards is not as powerful as the Mac CPU. The trouble is that 
nobody wants to write the (not so complicated) software to do it. 
You can charge $1000 for a CPU modem board; we all know 
that modems alone go for under $300. IBMers are being ripped 
off to the tune of $700. Slotted Macs have nothing to do with it. 
The same author also had trouble with copying files from his 
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RAM disk inFinder 5.3, to which the editor opined that the RAM 
disk was at fault. I have had similar problems with other Finders 
and no RAM disk. It has to do wwith the way the Finder handles 
hierarchical directories recursively. If memory is short, as it 
would be with a RAM disk installed, the Finder can get badly 
confused and sometimes even crashes. It's a Finder problem. 
BlockMove for Update Events 
Fernando Salazar 
Washington, DC 

Something in your May '87 issue caught my eye. Two articles, 
the ABC column and Pascal Procedures, used CopyBits to 
transfer off-screen bitmpas to on-screen windows. Bob Gordon's 
article uses CopyBits to manage Update events, while Gary 
Palmer's article uses it to scale whole MacPaint images. Both 
cases seem to exceed the 3K limit suggested for CopyBits in 
Inside Mac. What's the deal on this limit? Is there a way to 
determine how much is OK to copy? Programs like FullPaint 
seem to keep within the limit; when you paste into the scrapbook 
from FullPaoint, then from the scrapbook into MacDraw or 
CricketDraw, the pasteed bitmap appears as several objects 
about 3K in size. Paint Grabber, on the other hand, puts a single 
large bitmap onto the Clipboard. [CopyBits uses the stack, so 
limitations on CopyBits are tied to the available stack space. The 
suggestion of a 3K limit assumes a 6K stack space. If the 
application can guarantee the operation won't take more than 
half the available stack space, then there is no limit. -Ed] 

Ihave a program that uses off-screen drawing to reduce flicker 
in scrolling. Ituses BlockMove instead of CopyBits, first to make 
an off-screen copy of the current Port, then to move the modified 
copy back on-screen. This type of code isn't helpful for scaling 
an image, as is done in the MacPaint article, but for quick 
handling of update events, it should work fine. 


Procedure Of fScreenDraw; 


var 
currPort: GrafPtr; 
oldBits, tempBits: BitMap; 
aSize: Size; 


Begin (save current port, create off-screen bitmap) 
GetPortCcurrPort); 
oldBits:scurrPort^ .portBits; 
tempBits:=oldBits; 
With tempBits do 
aSize:=rowbytes * (bounds .bottom-bounds. top); 
tempBi ts. baseAddr :=NewPtr(CaSize); 
(copy current port bitmap to new one} 
HideCursor; 
BlockMoveColdBits.baseAddr, tempBits.baseAddr, aSize); 
ShowCursor; 
(Set currPort to off-screen bitmap and start drawing ) 
SetPortBitsCtempBits); 


( Put a proc that draws to CurrPort here ) 


( copy off screen bitmap to original) 
HideCursor; 
BlockMoveCtempBi ts .baseAddr , o1dB its .baseAddr , aS ize); 
ShowCursor ; 
SetPor tBitsColdBits); 
DisposP tr( tempBits .baseAddr ); 

end; 
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The Great French Cracker Scandal 
Special to MacTutor 
J. Langowskl 

[The following is the Editor’ s summary of a Bix post by Jórg 
Langowski, іп the Editor's own words.] 

The French developer community is up in arms over the arrest 
and trial of one of their own, for hacking and cracking several 
copy protected programs distributed in France. Two years ago, a 
French hacker by the name of Nourallah Goulamhoussen, who 
operated under the pseudonym of Faraglace (maybe it means 
something in French! ), pulled a “Simon Jester” move by cracking 
apre-release of Silver Surfer, alias 4th Dimension, and Excel. He 
also played around with the start-up screens and logos, leaving 
cute messages behind. Unfortunately, he got carried away and 
left his real name in there as well. ACI, the French makers of 4th 
Dimension, lead by their president, Marylene Delbourg-Delphis, 
known as Madame DD, brought suit, joined by Microsoft Corp. 
and Apple Computer. The three heavy weights claimed damages 
of $390,000 for “copying the brand name and damaging the 
brand image.” Yesterday the verdict came in: Nourallah was 
fined $3,300 for the criminal offense and ordered to pay $83,000 
in damages to the three “injured” parties. Since Nourallah is a 
student in Pharmacy, it is not clear how the three corporations 
plan to collect from him. Since 4th Dimension is now being 
distributed in this country unprotected, and Excel has been 
unprotected and cracked for years, the whole thing sounds like a 
tale from Alice in Wonderland. Unless you happen to be a 
Pharmacy student by the name of Nourallah Goulamhoussen. 

Look What | Found! 

The problem for Nourallah seems to be that he did this 
hacking and cracking a long time ago, back when we all knew 
very little about the Mac and it’s operation. What did him in, is 
that his cracked copies of 4th Dimension and Excel were picked 
up by three legitimate crooks, who collected pirated software, 
published a catalog of them and sold them for profit. Nourallah 
had no idea they were using copies he had cracked. The pirate 
catalog included MacWrite, MacPaint, and a lot of other pro- 
tected software besides the two that carried Nourallah’s han- 
dywork in them. ACI and Microsoft went after Nourallah 
because “he made it possible for the other three to copy the 
programs” ; in other words, as an example to other would be 
software crackers who break protected programs. Gee, if they 
tried to go after people like that here, they'd have to arrest half the 
country! (How many times have you used Copy II Mac or Hard 
Disk Utility lately?) 

Everyone seems to agree the three bad guys deserved to be 
prosecuted, but what the French Macintosh community can’t 
understand is why they went after Nourallah? He had nothing to 
do with the three software pirates and certainly never profited 
from any of their activities. 

French Software Madam 

This “Madame DD” of ACI is apparently quite a character in 
this whole charade. At the trial, she summed up her feelings by 
saying ".. from my point of view, those people are nothing but 
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flunked-out developers, evil individuals..., any turkey who 
spends enough of his time will eventually deprotect a product!" 

Her opinion of the need for backup copies was expressed in 
another remark: "Oh, sure, some would like a backup of the key 
disk just in case... Only the probability that the user destroys his 
key disk is almost zero and, in 9 out of 10 times, such demands 
come from dishonest people who want two disks for the price of 
one." 

The Madam also has a few words to say about a software 
company's responsibility to replace defective media: "Nothing 
forces us to replace a program. If you crash your car or your 
Mac, the manufacturer won't replace it, even if they are abso- 
lutely necessary for your work. You spill coffee on a book, you're 
not going to ask the publisher to send you a new one, but you do 
it if it's been a program. Why should software be treated 
separately?" 

Getthe idea that Madame DD is a bit behind the times? Rumor 
has it that ACI developed a list of people who had the ability to 
crack software protection in France so they could send them 
threatening letters. The fact that Apple and Microsoft were party 
to the "de-frocking" of Nourallah, who certainly did not have the 
means to adequately defend himself against such mammoth 
corporate power, has to send a chill down the back of every 
freedom loving programmer. Will some teenage software hack- 
ing come back to haunt you some day to the tune of $100,000? 
Simon Jester, you ever get back all the copies of your bootleg SJ 
disk #1? 

What's All the Fuss? 

The final irony of this is the fact that the French version of 4th 
Dimension is a heavily protected piece of buggy software that 
crashes regularly. Nourallah's copy was a very early pre-release 
version of this thing. Apple, and now ACIUS, has spent a year 
working to get the thing debugged here in the US and the product 
is so close to final release (shipping began the day this issue went 
tothe printers) thatone has to wonder *what's all the fuss about?" 
There is talk in France of taking up a collection to help Nourallah 
pay his $83,000 debt, and hire a decent lawyer for an appeal. 
Certainly, Microsoft has to look pretty ridiculous in this thing, 
since Excel is not even copy protected over here. The idea that 
this poor student is going to make Bill Gates a little bit richer than 
his six billion dollars makes him now is a little unnerving. Bill, 
why don't you make a charitable contribution, and forgive this 
guy his debt? 

French Reaction 

The French reaction was summed up on the CalvaCom 
bulletin board by Jean-Benedict de Saussure, who said, "That 
Apple helps to pursue those crooks who sell illegal copies, or 
those who use software which they didn’ t buy, makes full sense. 
But that the consequence of this would be to crack down on a guy 
whose main fault is to have been intelligent enough to arrive at 
alevel which others had never reached, that is hard to swallow." 

And finally, this remark from our Editorial Board member, 
Jórg Langowski: "Microsoft, Apple and ACI seemto have chosen 
to constitute an example of an individual who didn't have the 
resources to defend himself. He played around with some soft- 
ware, trying to understand how it worked. His 'handywork' got 
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in the hands of others, who without his knowing, made money 
from it. He was not tried for stealing software, but for making it 
possible for others to steal it. We are paying a 'shareware 
lawyer’ and collecting for an appeal. .. meanwhile, quite afew of 
us have decided to give up using the software of certain compa- 
nies, especially since there are often cheaper, unprotected pro- 
grams that do a better job." 

Have an opinion? Send it to: 

Jórg Langowski 

EMBL, c/o I.L.L. 156x 

F-38042 Grenoble Cedex 

France 

Update on Lightspeed C & Pascal 
Special to MacTutor 
Andrew Singer 
Think Technologies 

[The following is the Editor' s summary of a phone conversa- 
tion with Mr. Singer.] 

Let me take this opportunity to bring all of our MacTutor fans 
up to date on Lightspeed C and Pascal relative to the Macintosh 
II. We have been working very hard to get both products up to 
speed with both the new Macs and the new operating system. 

Surprise! Everything you knew 
is now wrong, again! 

What many people may not realize is that Apple really pulled 
a fast one on the developers when they released system 4.1. This 
system was completely different from the beta version system 4.0 
that we were working with on the early beta Macintosh II 
machines, seeded to developers so they could port their software 
over. And what made matters worse, the production Mac II units 
turned outto be very much different from the pre-production seed 
models, and nothing at all like Inside Macintosh Volume 5 
described. (I'm sure David Wilsoncan sympathize with this as he 
attempts to prepare his Mac II programming seminar!) 

Last Minute Changes by Apple 

We found that things that worked fine on the seed machines 
under system 4.0, now crashed on the production units under 4.1, 
especially in the area of the menu manager. Another problem has 
been the late shipping of a final version of the traps and equates 
files. As a result, we found ourselves calling Apple and saying, 
"Did you know the new system does such and such?", to which 
they would reply, “Oh, really? Let me get back to you on that...” 
so obviously, even the people inside Apple were having trouble 
finding out just what changes had been made to the operating 
system in the new version. 

Hurry ир and walt 

Apple figured those developers who had seed machines 
didn't need the production machines as quickly as those without, 
so we got moved down the pecking order. We finally just went 
out to a local dealer and bought one off the shelf to speed up the 
conversion process. This wouldn't have been a problem if the 
production machine hadn't been so much different from the seed 
machine. 

It didn't help matters much either when Apple released 
system 4.1 to the public without any warning to developers as to 
the impact they could expect from the new system. At the same 
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time we found things breaking under 4.1, we started getting calls 
from our customers that their software wasn't working. It would 
have been nice if Apple had given the developer community 
some time to adjust to version 4.1 before making it public. It 
would have been even nicer if Apple had released documentation 
alerting us to the impact of changes under 4.1. But even Apple 
itself does not seem to have fully documented anywhere, the 
system changes we are uncovering in our development work. 
Lightspeed C 

The current version of Lightspeed C, 2.01, runs under system 
4.1 on the Mac II but has some problems with the glue routines 
for the new system features. We have received the beta glue 
routines from Apple, the same as those being shipped with MPW 
and we are preparing interfaces to them for LS C. A new beta 
version of LS C with the new library interfaces will ship within 
a week. This upgrade utility will make LS C 100% Mac II 
compatible. The upgrade will be posted on Compu-Serve (it was 
posted the day this issue went to press) and will be available 
through our dealers, including MacTutor. Incidentally, these 
new routines have very little resemblance with Inside Mac 
Volume 5, so beware. Apple really needs to upgrade Volume 5 
so that it reflects reality! 

No Switcher With 4.1 

One thing that is not supported by the new system is switcher. 
Apple has made extensive changes to the system dependent 
portions of the Mac so that switcher no longer works. Unfortu- 
nately we can’t do anything about that. Apple has made the 
decision to abandon switcher for now until their own future 
Finder upgrades are ready. This was probably to be expected. 

Weare also working on a major new release of LS C, beyond 
this Macintosh II correction, which will add significant new 
features. We don’t think that will be ready for the Boston 
MacWorld Expo, but are hoping to release it as soon as it is ready. 
Meanwhile, we will have a major new software tool for 
developer’s to show at Boston. 

Lightspeed Editor’s to be Released 

Weare announcing the release of a new product calld capps’, 
which makes the Editor technology of the Lightspeed C and 
Pascal products available to developer's both as a stand-alone 
library and as commented source code. capps' is based on а 
software library called “РЕ” (Program Edit) that we created 
because the Macintosh Toolbox's TE (Text Edit) package didn't 
provide the performance or the functionality that we wanted for 
the integrated editors in THINK's LightspeedC and Lightspeed 
Pascal. capps’ will also include a library called “grep” (who 
knows what the acronym means) that implements the fancy 
pattern-based search and replace features in LightspeedC. As 
you can well imagine, both libraries have been carefully crafted 
to deliver exceptional performance. Our languages depend on 
them!! 

capps' consists of the same PE and grep libraries actually 
used in THINK'sLightspeed language products, complete docu- 
mentation for those libraries, and two complete, ready-to-use 
standalone editors implemented using them. The first, PEdit, is 
a fully featured program editing application similar to the editor 
in LightspeedC. The second, “Apple Edit", is a handy desk 
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accessory style program editor. Machine-readable source code, 
extensively commented, is supplied for both editors. Versions 
will be available for both LightspeedC and Lightspeed Pascal 
users. The price has not been fixed yet but it will certainly be 
under $100. 
LS Pascal 

Lightspeed Pascal, version 1.0, does not work under the new 
system. However, we have been shipping a beta version 1.01 to 
all our customers who call and ask for it. This version runs on the 
Mac II if you use itas a traditional compiler; build the application 
first, then run and debug it externally from the LS shell. If you try 
to run your application under the LS debugger shell, our context 
switching from your application to the Lightspeed application 
causes the Mac II problems because we are not resetting all of the 
new system dependent globals that are context sensitive. The 
problem is, Apple won't (or may not know themselves!) tell us 
all the system parameters that are context sensitive, and so we 
have had to dig them out by hand. 

Context Switch is OS Dependent 

Lightspeed Pascal works by doing something similar, but 
more sophisticated, than switcher. This is how your application 
can run while under control of the LS shell, giving it the 
wonderful source level debugging we've all come to know and 
love. Butthis developer friendliness comes with a price. Take for 
example the problem of the menu bar. For a context switch, you 
need to display one menu bar for the application, then revert back 
to the compiler's menu bar. Normally you would do a Get- 
MenuBar followed by a ClearMenuBar, but if you do that, you 
won't be able to get your previous menu bar back correctly. The 
semantics of these operations have changed, partly because of the 
color additions to the menu manager. Apple has not documented 
these effects, and they really only apply to applications like ours 
that are trying to manipulate and control the system environment. 
We've had to disassemble the new ROMS to find out what the 
Mac is doing to us. If you are having problems in your own 
software development, look to the menu manager as one possible 
Source, as that has been radically altered. Many of the changes are 
very subtle, and while Apple has been very cooperative when we 
call, we've had to do all the research to find those subtleties. A 
lot of reverse engineering has been done to make sure we have 
identified all of the context sensitive system parameters that must 
be reset when switching from the application environment back 
to the Lightspeed environment. МасТшог has asked us to iden- 
tify some of the things we've found which may be of interest to 
other developers, and we will try to get an article out on what 
we've found. 

New Pascal Beta for Mac Il 

The bottom line is that we have succeeded and are happy to 
be able to say that Lightspeed Pascal is just a few weeks away 
from anew betarelease that will be completely 10096 compatible 
with the Mac II and will support the new libraries. Like our LS 
C, we will have an upgrade utility that will convert Pascal to the 
new version. 

We also are working on a major new release of Lightspeed 
Pascal with some exciting enhancements to our already user 
friendly debugging environment. There has been a lively debate 
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in MacTutor about the various 32K limitations that the Mac 
segment loader imposes on development systems. Last month it 
was incorrectly implied that LS C cannot index arrays declared 
on the heap with NewHandle, greater than 32K. This is not true. 
LS Cwill workcorrectly in the same manner as was described last 
month for MPW C. The current version of LS Pascal, however, 
does not allow you to index a NewHandle array greater than 32K, 
but this is being fixed and will be available in the new major 
release of Pascal we are working on. That version will support 
indexing large arrays created on the heap just as C does. 
Apple Needs to Do Their Homework 

One thing that is needed from Apple is a statement about 
where the segment manager will go. Global variables are refer- 
enced relative to A5. While we could allow local variables to be 
declared greater than 32K, getting global variables and segments 
greater than 32K requires changes to the Mac operating system 
that only Apple can make, if we are to continue using the segment 
loader, which is our intention. We hope that Apple will be more 
communicative about how they plan to modify the segment 
loader and memory manager to move the Mac into the 32 bit 
world. If you have any questions, drop usa line on Apple Link or 
give us a Call. We are fully committed to making our LS C and 
Pascal as powerful, friendly and compatible as possible with all 
present and future Apple products. As was reported last month, 
our phone and address have changed: 

Think Tech. 

135 South Road 

Bedford, Mass 01730 

1-617-863-5595 

Apple Link: X0121 

Apple Releases New Upgrades 
Apple Press Release 

Apple has released a new version of MacDraw (1.9.5), 
MacTerminal (2.2) and MacProject (1.2). They are available free 
from Apple dealers to customers who have an original disk with 
an original label. They have also said MacWrite (4.6) will be 
available sometime in August. No mention was made of 
MacPaint. The new versions have been fixed to work with the 
Macintosh II and SE. A few other additions were also included 
including the ability of MacDraw to use 54 fonts! In addition, the 
products are said to be AppleShare compatible. Draw, Write and 
Project are being turned over to Claris, the new Apple Software 
company (not to be confused with Acius with is marketing 4th 
Dimension). MacTerminal has been judged to be “system soft- 
ware” or something close to it and will remain within Apple along 
with AppleShare. A lively debate is also going on over Hyper- 
Card, the new Bill Atkinson data base product. Some say it 
should remain with Apple, others say it should go to Claris. The 
introduction of two powerful data base products (HyperCard and 
4th Dimension), initially promoted by Apple Computer should 
heat up the software market in coming months. 

MacTerminal Patch Update 
Monty Solomon 
Lotus Development 

The MacTerminal patch published last month incorrectly said 

you should change four instances of 02B6 to 0A78 to fix the 
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BasicGlobs global parameter conflict. Actually, only the last 
instance, 0000 02B6, should be changed to 0000 0A78. The other 
references are not to the global variable location and may cause 
erratic behavior. [Get version 2.2 now. -Ed] 
BlockMove versus CopyBits 
Larry Rosenstein 
Apple Computer, Inc. 

I recently received the July 1987 MacTutor, and wanted to 
comment on a letter from Fernando Salazar on page 11. 

His code, which uses BlockMove instead of CopyBits to 
manipulate bitmaps, is a good example of why programs do not 
work on new machines or new System versions. The reason 
MacPaint, FullPaint, etc. don’t work оп acolor screen is that they 
draw directly to the screen and bypass Quickdraw. 

The code in the letter does not take into account the width of 
the bitmap bounds (which may be different from the rowBytes), 
the depth of the screen, the clipping, etc. He also does not shield 
the cursor, which is necessary if you draw directly on to the 
screen. (The result of this will be duplicate cursor images.) 

I was able to get more than adequate performance out of 
CopyBits in my MacApp Paint program. It is interesting to note 
that this program works fine on a Mac II with any screen depth 
(although it works much faster with a 1-bit deep screen). On a 
MacPlus (and especially a Mac SE, which is 20% faster), the 
standard CopyBits can refresh the entire screen very quickly, if 
you take advantage of Quickdraw's optimizations. In particular, 
you should use srcCopy mode, a NIL maskRgn, and ensure that 
the source and destination bitmaps are aligned at the same 
boundary. 

The letter also talked about the 3K limit mentioned in Inside 
Macintosh. There are 2 things to consider here. First, is what 
Fernando Salazar alluded to. If you call DrawPicture of a picture 
containing a CopyBits call, QuickDraw normally will allocate a 
heap block to contain the bitmap. The reason is that bitmaps are 
stored compressed in the picture, and QuickDraw uncompresses 
the bitmap before moving it into the destination. 

Because of this, a courteous application will generate a 
picture containing small CopyBits calls. If you break up a large 
CopyBits into a series of smaller ones, then the drawer of the 
picture will not need as much heap space to draw the picture. 
Applications that do this, should insert picture comments to 
indicate that the small CopyBits are really parts of one large 
bitmap. This is discussed in Technical Note #27, which deals 
with the picture comments understood by MacDraw. 

The other question is whether CopyBits itself uses any stack 
space. My experience with MacApp Paint is that in some cases 
the answer is NO. My program calls CopyBits with large (55K) 
bitmaps and no problems. (I also do not reserve 27K of stack 
space.) Similarly, the Window Manager in the ROM uses a 
single CopyBits calls when you move a window on the screen, 
regardless of the size of the window. 

In both cases, however, these calls to CopyBits use srcCopy 
mode and a NIL mask. Other uses of CopyBits, for example one 
with a non-NIL mask or one that requires stretching or shrinking 
of the bitmap, could conceivably require stack space. I am not 
familiar enough with the internals of QuickDraw to know the 
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answer. Chris Derossi of Apple Technical Support, however, 
would know the answer. I would like to see him answer that 
question in one of his MacTutor columns. 
32K Heap Arrays 
George A. Nelson 
Arlington, MA 
I have followed with some interest the thread in the Letters 
column about 32K limit on static data. I have a solution to this 
problem that has helped others; it not only completely bypasses 
this limit, but shrinks affected programs by up to 32K, as well! 
The Macintosh, unlike past personal computers, includes a 
Memory Manager that manages a large "heap" of free memory. 
The preferred way to make a large array is to request that storage 
from the Memory Manager, placing it in the heap, rather than on 
or above the stack. Thus , a program that currently has a problem 
with a 32K limit on static arrays can be fixed by changing: 
static int myArrayl 160001; /* wanted 100000 */ 


to: 


stetic int *myArray; 
nainC) 


( 
my Array = NewPtr( 100000 * sizeofCint) ); 
if С !myArray ) 
error€ “not enough memory” ); 


х = myArrayl27); /* e.g. */ 


) 

Note that (in C) although the declaration of my Array has been 
changed, none of the references to it are affected. The situation 
in Pascal is similar, provided the compiler does the correct 
address calculations. The situation in FORTRAN is (I think) a 
little harder; I know that it will work to pass the array as a 
parameter to the procedure that needs it. 

NewPtr is the appropriate call to replace a static array. If 
there are several such arrays, or if their size changes during 
execution, NewHandle should be used instead (but know how, 
first). 

How does this save 32K? All Macintosh compilers with 
which I am familiar, with the sole exception of Consulair’s Mac 
C, store an image of the declared static data in the application. 
(Consulair stores a compressed image.) By allocating the storage 
for the array in the heap at run time, we no longer need to store 
32K of zeros in the application! The technique is worth exploit- 
ing even for smaller arrays, as long as they are not initialized to 
more interesting values. 

ZBasic Woes 
Ronald Lowrance 
Hawthorne, CA 

Ihave had so much trouble with ZBASIC, I feel I need to warn 
other Mac Developers. I have already gone through 4 very bugy 
upgrades and 1000 work arounds. I give up! Can anybody out 
there even get (v3.03+) 

INDEX$D(element#[,index#]) 

to be recognized by the compiler? Jeff at Zedcor couldn’t 
help. After 3 phone calls, he finally told me he didn’t have a Mac 
to try it out; and could I mail them aexample program. Have you 
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ever called acompany up about their product and had that feeling 
you knew more about their product than they did? The only 
answer I ever get is ‘get the next upgrade’. Well, I’m not going 
to. They can keep v4.0. Forget ZBasic! I wish Inever left MDS! 
[Dave Kelly likes 4.0! -Ed] 
MS Basic Woes 
Steve Meuse 

Here is a compilation of the letters I’ve sent to Microsoft 
regarding problems with the Macintosh Basic Compiler 1.0: 

* Files created by the compiler default to “Edit” as their 
creator. The interpreter by default creates files with no defined 
creator. 

* The FILES(1) statement, with filespec omitted (or a null 
string) is documented as displaying all files on a drive, and the 
interpreter does this. Sometimes compiled code displays only 
text files under these conditions, and sometimes it works as it 
should. Itappears to be acompile-time error, as a given compiled 
program behaves consistently: it either always works or always 
fails. 

* When a program is running on the non-startup drive, the 
interpreter will find LIBRARY files in the root directory of the 
startup volume. Compiled code will not. 

* I’m using a library called MIDIBASIC. The statement 
MIDIout X% AND F% works under the interpreter, but gener- 
ates a type mismatch with the compiler. It seems the compiler 
isn't passing an integer to MIDIout. The alternate statement, 1% 
= X% AND F% : MIDIout 1%, executes properly however. 


* Run this test program: 
XKKKKKKKKKKKKKKKKKKE 


FOR 1% = 1106 
1% =012-1220 
WINDOW i$,,(2*j$,41*j82-(259*j$, 179458), 1 
BUTTON 1, 1, *Теѕі Button", (28, 28)-(239, 40) 
NEXT 


LOOP: 

1$-DIALOGC2O) 

IF 1%-3 THEN WINDOW DIALOGC3) 
GOTO LOOP 


ЖЖЖЖЖЖЖХЖЖХАХЖЖЖЖЖЖЖЖЖЖ 


Under the interpreter, all is fine. When compiled, click on 
some windows to bring them to the front. Then click on windows 
5 or 6 (the two rightmost windows). The compiler-generated 
program doesn’t redraw the buttons contained in these windows. 
The same goes for edit fields placed in windows 5 or 6. Also, 
windows 5 and 6 can't be dragged. 

* I’m using SaveArray to save user preferences into the 
resource fork between prgram uses. For some reason, repeated 
use of the SaveArray saves multiple resources with the same ID 
number. I worked around it using GetRes, RemoveRes, etc., but 
is this the way it should be? 

* Using the CLEAR,xxx statement under the interpreter 
allows me to create a larger system heap, so I can process some 
medium sized bitmaps (Apple ][ bitmaps , actually). For some 
reason, this isn't true in the compiler. I read the addendum note 
about only having 3500 bytes available for the clipboard- surely 
there's a way to enlarge that, but it sure doesn't seem to be 
CLEAR. Any suggestions? 
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* You might want to mention in the docs never to use 
CloseResFile if an application stores is resources in its own 
resource fork. This cuts off the program's path to the quit code, 
and it hangs after the menus revert to File and Edit. 

* I’m using System 5.3 with the appropriate Imagewriter 
system file. If I type Command-period while a printing job is 
executing, the Print Manager should simply close up shop and 
return to the application. This works well under the interpreter, 
but the compiled code often fails with an error #57. This happens 
with break trapping on or off. 

A few observations: 

* The string-to-numeric conversions are substantially slower 


when compiled. This test program: 
ЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖЖ 


DEFINT I-J 

START=TIMER 

A$-SPACESC 10000 ) 

FOR 1=1 TO LENCA$) 
J-ASCCMID$CAS, I, 102 

NEXT 

PRINT TIMER-START; ^ Seconds” 

WHILE МО05Е(02-0 : WEND 


ЖЖЖЖЖЖЖЖЖЖЖЖХЖЖЖЖЖЖЖ 


executes in 29 seconds interpreted, 224 seconds compiled. In- 
stead of being 2-3 times faster, the compiled code here is 7-8 
times slower! 

* A smarter linker would be a boon. The math pack is linked 
regardless of whether math is actually used in a program. Natu- 
rally, nearly all programs use some of the common operators, but 
a good first step would be to link in the trancendentals only if one 
is used. Ibelieve this could substantially reduce the final size of 
many compiled programs. 

Microsoft employees have been polite in replying to these 
points, though there's little they can say besides “Thank you”, 
and "We һауе no workaround at this time". Anyway, there are 
some problems here I haven't seen mentioned in MacTutor, so I 


wanted you to know. 
LS Pascal & MemError 
Mark S. Jennings 
Louisville, CO 


Users of Lightspeed Pascal (V 1.0) should be careful of LSP's 
tendency to reset the memory manager's MemkError variable 
behind the application's back. For example, the following 
program (whichattempts to allocate a gigantic block in the heap), 
correctly writes then memFullErr (-108) error number: 


program LSPprob; 
var 


h : handle; 
begin 
Showtext; 
h := NewHandle (MaxLongInt); (should always fail) 
writeln(MemError); (should always write -108) 
end. 


However, the following functionally equivalent program 
when comp[iled with the debug option on indicates that no 


memory error occurred: 
program LSMemProb; 
procedure WriteMemErr; 
n 
writeln(MemError); (writes Ø if debug off) 
end; 
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var 

h : handle; 
begin 

ShowText; 

h := NewHandle(MaxLongInt?; 

Wr i teMemErr ; 
end. 

If you turn the debug option off, it works as it should. 
Apparently when you have the debug option on, LSP calls the 
memory manager on entry to any procedure or function. This 
causes the MemError variable to be reset to zero and you lose the 
ability to check for memory allocation errors. If the code which 
checks MemError resides in a seperate module, you need to turn 
the debug option off in the called module only; the caller can still 
set debugging on. 

LSP needs to preserve the application's value of MemError 
(and possibly other error variables like ResError) and restore 
them before and after it gets done screwing around with the 
system. 


(should always fail) 
(should always write -108) 


Mac Programming a Mystery 
Lon Byrne 
APO San Francisco, CA 

I have been reading your mag. for a couple of years now and 
figure its time to pay for my own way. Thanks for the information 
you have included in your past issues. 

I am still in the dark about the “Big Picture" of the Mac 
software even after reading both Macintosh revealed books and 
"How to write Macintosh software’. I have had previous knowl- 
edge of Apple ][ stuff down to the assembly level and solve most 
peoples problems on both the Apple ][ and Mac, but I have the 
uneasy feeling on the Mac of flying blind most of the time. Like 
walking donw a dark alley and waiting for something to jump out 
and zap you. 

Anyway thanks again. If you can think of a solution to my 
lack of scope in the above problem please tell me. Help........... if 
not I'll struggle along and hope that someday there will be a 
bright flash of light and the great god of ROM will smile on me. 

[Sit down and type in the text edit program in the January 
1987 issue of MacTutor, then modify one of the menu items in the 
program. After doing that, you'll either get the big picture or 
decide to take up golfing! -Ed] 

Power Supply Comments 
Terry Gritton 
Watsonville, CA 

The articles by Loy Spurlock and Chuck Rusch on the analog 
board/upgrade situation were interesting. I have been using a 
Max2 upgrade for 16 months and couldn't live without it, but the 
screen has a tendency to skew to the left in the lower left corner, 
especially as the Mac warms up. Also I can't get the 5 volt 
adjustment above 4.9 volts. Maybe replacing the CR17 diode 
willsolveboth problems. I wish there had been more information 
on balancing the 5 and 12 volt supplies. 

With the price of 1 megabit DRAM's starting to drop, I am 
tempted to populate the remainder of the Max2 board (for 4 
Mbyte memory) but wonder if the power supply is up to it. 
Certainly more cooling will be needed. Along those lines I 
mention that Edmund Scientific offers those piezo electric fans 
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for $12.00 apiece or 3 for $33.75. Just add $7.00 for postage and 
handling and the cost of some micro-hooks to connect to the 
110vac at the power switch, and one could coolout the Mac for 
less than $50.00. 

[I don't think those piezo fans are worth anything. -Ed] 

Window Detail 
Clifford Story 
Murfreesboro, TN 

Here's an obscure little incompatability I've just found. If 
you set up a window with a zoom box, and then run your program 
onanold-ROM machine, using System 2.0, the grow box doesn't 
work! (Why would you want to do that? Well, it might not be 
you; it might be someone else using your program. And maybe 
the machine is a 128 - Applerecommends System 2.0 with a 128.) 
What apparently happens: the WDEF doesn't recognize the 
window type (8) and uses the next one on its list instead (4: 
nogrowdocproc). “Findwindow” returns "incontent" if you click 
in the grow box. My work-around is to include two window 
resources in the program. Then I check $28E before opening a 
window, and use the standard document window instead of the 
zoom window if I'm running on an old-ROM machine. 

I've had Mac C Jr. for several weeks, and I think my long 
search for a good C compiler is over (I also think C is the wrong 
language for programming the Mac, but I want to write one major 
program in C, just so I can say I didit). A week after I got the new 
compiler, I gave Lightspeed C away. The most interesting point 
of comparison between the two: Mac C isalotfaster. Anyway, 
other Mac C Jr users may want to know that while there is no 
“‘list.h” file, the library includes list manager glue. Just write your 
own include file. I discovered this by writing my own glue and 
getting link errors. Also, the manual does not mention that a 
"pascal" function passes points by value. 


Icon Reader Needs Work 
John Holder 
Anaheim, CA 
I just wanted to point out a couple of things about the article 
"Icon Reader Uulity" in your June 1987 issue. Number one, there 
are a few instances that the stack pointer is not incremented after 
a Trap call has been made (in the IconDraw MACRO after 
_GetIndResource, in the Miscellaneous initialization section 
after GetResource, after OpenResFile in the SearchIcon rou- 
tine, & after CountResources in the ValidName routine). 
Also, there is something I'd like to point out to assembly 
langauge programmers. You shouldn't be using "Define Con- 
stant" (DC) as a way to store variables (only use this to hold 
Constant values!), instead, use "Define Storage" (DS) when the 
value is going to be changed in the course of your program. 
Programs that try to modify locations in their own code will not 
work оп the new Macs and it's not a good idea to do anyway... 
Life in the Font Factory 
Michael Mace 
Berkeley, CA 
А few gripes on the new Pagemaker: much of my time now 
is being devoted to getting all our fonts to work again with 
PageMaker 2.0 and the new driver. It is clear that PM's line 
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layout algorithms have changed. Wonderful! In addition, it 
downloads fonts inconsistently, and will not italicize anything 
downloadable (try it with Saratoga). It doesn't help any that the 
guy who wrote the driver for them took a five-week vacation as 
soon as 2.0 shipped. Did he know something? 

You might ask how these major bugs managed to slip 
through, when we are an Aldus beta tester. Let's just say that we 
would have caught all of them, if Aldus had ever sent us a 
working copy of the program to test. All the ones we got were so 
bug-ridden that they could not print at all. Clearly, they rushed 
the product at the end. I don't blame them (they were running 
late), but I am beginning to believe that the Mac operating 
environment has become so complex that it is almost impossible 
to ship a major product without bugs in the first release. Witness 
Word, PageMaker, Cricket Draw, Xpress, etc., etc. Maybe 
people who buy version 1.0 of a program should get a discount. 

Well, they'll straighten out PageMaker, but it sure is a 
problem for now. Thought about trying Xpress? I know that's 
heresy in some circles, but it is competitive (please note that Iam 
not taking sides). 

On tothe next gripe: PICT versus EPSF. I'll go on record here 
as saying that the EPSF formatisa waste of time, made necessary 
solely by shortcomings in Apple's PICT format (and Apple's 
failure to document clearly those features that exist). After all, 
what is the PICT format? The standard way to transfer pictures 
between applications. Why do we need another format? Isn't 
this the sort of confusing foolishness we sneer at in the IBM 
world? 

The Great PICT versus EPSF Debate 

First, a little backround: EPSF was invented by Jim Von Ehr 
of Altsys (Fontographer) a long time ago. Jim is a very bright 
guy, and he perceived very early a need for a good way to transfer 
PostScript code between applications. His EPSF format calls for 
PostScript text to be stored in the data fork of the file in question, 
and a PICT (for display on the screen only) in the resource fork. 

Jim was correct that there was no published format for 
PostScript transfers. However, Apple already had an internal 
working document describing how PostScript could be included 
in PICTS, primarily by putting the code into handles pointed to by 
comments. The format allows you to mix PostScript and Quick- 
Draw, or to specify PostScript to be substituted for QuickDraw 
when necessary. 

I know the documentation existed because I saw it more than 
a year ago. Tech Support was perfectly happy to send a photo- 
copy to anyone who asked. The document has just recently been 
released in tech note format, finally. Why Apple waited so long, 
I don't know, but the delay created an impression that there was 
no format for transferring PostScript, when in fact there was. 
Thus Adobe ended up endorsing EPSF as gospel, and now it is 
being pressed as a de facto standard for doing something awk- 
wardly that we can already do easily. 

Using the PICT format has several advantages over EPSF. 
First, most of the applications already out there can include 
PICTs in documents, at least pasted from the clipboard. Second, 
PICTscan becopiedeasily into and out of the Scrapbook (as long 
as they aren't too large). Third, when you print a PICT you 
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already have the drawing's bounding box, but to get it out of an 
EPSF you need to parse the PostScript data (not too difficult, but 
an annoyance and waste of programming time). Finally, PICTs 
allow you to mix QuickDraw and PostScript, so that you can, for 
instance, use the built-in routines for text manipulation in Quick- 
Draw, and then just do in PostScript whatever the Mac cannot 
handle. 

Ithink these arguments are pretty convincing, but I' m not the 
last word on desktop publishing software. We need to have a 
discussion among developers, and pick a single format. When a 
format is picked, we need to pressure Apple to implement if fully. 
Here's a list of some of the troubles with each format: 

PICT: 1. It's unclear how the PostScript code being included 
in the PICT can tell where it is on the page. The current point 
should be set to one corner of the bounding rectangle when 
control is passed to the code in the PICT. This way the code will 
be able to draw everything relative to that starting point. Or, 
better yet, move the coordinate origin to one of the corners. 2. 
Some application writers, in their infinite wisdom, wrote PICT- 
interpreting code which strips out PICT comments when they are 
pasted in. So if you paste PostScript PICTs into most of the major 
drawing programs, the programs will strip out the PostScript. 
Application writers should include both a Paste command which 
interprets the PICT, and a Place command which would just put 
a PICT onto the page, unaltered. This would make the applica- 
tions compatible with future additions to the spec. 3. The 
Scrapbook and the Clipboard need to be modified to accept very 
large PICTs. 

EPSF: 1. This may be unrealistic, but I would like to be able 
to mix PostScripe and QuickDraw. 2. We must be able to cut and 
paste EPSFs using the Clipboard. 3. The entire application base 
must be rewritten to accept EPSFs. 4. The format should be 
rewritten so that the application does not have to parse the 
PostScript to find out simple things like the bounding box. This 
should be put in a little resource where we can get it easily. I 
would love to hear what your readers think on PICT versus EPSF 
formats. 

Fate of the Unloved Hardware 
John K. Calhoun 

Do you suppose readers would enjoy something out of the 
ordinary? 

Recently I upgraded my 512 to an Enhanced and discovered 
to my chagrin that the Habadisk external single-sided disk drive 
no longer worked with the Mac. Worthless as hardware, I 
supposed that the Habadisk might be a fit subject for verse. 

In the unlikely event that anyone is so moved by this as to 
inquire of the outcome, the unfortunate disk drive was rescued by 
a5120wner (for $75 anda promise that I'd write no more poetry 
about it), who has since passed it along to yet another owner. The 
last I heard is that it still whirrs and grinds and stips out disks with 
as much character as ever. 

Keep up the good work. MacTutor is a first class publication. 
[This should strike a familar cord among all Mac owners as we 
witness the passing of yet another system upgrade era of confu- 
sion. -Ed] 

The Ballad of the Datakludge 


652 


John K. Calhoun 
Now gather round you hackers all 
This penitent to shrive, 
For I must tell the doleful tale 
Of my external drive. 


Remember news of Macintosh, 
Both rumors and reviews, 

Of insufficient memory 

And one disk drive too few? 


I swapped my disks a thousand times 
Just as it importuned; 

I shouted imprecations as 

My swelling thumbs ballooned. 


Insertions and ejections!—When 
I lost all hope of stopping, 

I sought a cheap external drive 
And stay of endless swapping. 


I settled for a lesser make 
Whose cost was not so dear— 
The dire debts of Macintosh 
Had sapped my cash that year. 


I know, I know you’ll mock me now, 
You'll say I was unwise. 

You'll scorn my awkwaard Datakludge— 
I see it in your eyes. 


Yet I withstand the bald contempt 
In your derisive voice. 

She’s not a thing of beauty but 

I don’t regret the choice. 


I doted on her homely quirks 
—Endearing imperfections— 

Her winking lights and angry noise 
And furious ejections. 


And never, till that fateful day, 
She never failed in duty, 

And faithfulness is far above 
The attribute of beauty. 


And so my tale should now conclude. 
But sadly it does not, 

Because I wasn’t satisfied 

To stick with what I'd got. 


For all had changed. I heard the news 
And fell into a swoon: 
"Enhancements to the Macintosh 
Available real soon." 


Insidious announcement! Oh!— 

I quivered as I heard, 

For hackers' passions are inflamed 
By just the merest word. 


The poison of desire tipped 
The press release's dart: 

I harkened to the luring news 
And lusted in my heart. 
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I hastened to embrace the bane 

That cruelly sundered us: 

New ВОМ” don't speak her language so 
She can't get on the bus. 


I damned my fat upgraded Mac 
In agitated state, 

For incompatibility 

Had sealed poor Data's fate. 


Anon she disconnected lay 

In catatonic mode— 
Inop'rable and obsolete 

And shunned by system code. 


And I, I am the faithless one; 
I don't deserve her graces. 
And so I seek the kinder Mac 
With which she interfaces. 


Are any of you unseduced 

By innovation's cry?— 

“I never rest, what's new is best, 
So goggle and then buy!” 


Oh, wisest hack, who harkens not 

To hype but to his reason, 

Please take her home and hook her up 
And mitigate my treason. 


For you can cleanse my conscience of 
Its shameful stains and dapples— 

Oh, waken her with gentle bits, 

And comfort her with Apples. 
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Plotting Small Icons 
David Dunham 
Goleta, CA 

A frequent question on the networks is, “how do you draw 
small icons (SICNs)?” A quick look at a SICN resource shows 
it to be simply the bits of the images. SICNs resemble ICN#s in 
that there can be multiple small icons in the same resource, but 
there is no count, and no data is presumed to be a mask. Each 
image is 32 bytes of data. So the SICN with ID=-15744 (in the 
system file), has the hexadecimal representation: 

0000 0000 ЗРЕО 48A8 48A4 4824 47С4 4004 4004 4104 4824 4824 4824 
3FFC 0000 0000. (See figure 1) 

This is the sort of bit image which CopyBits() manipulates, so 
drawing the SICN is a simple matter of stuffing the appropriate 
bit image into a BitMap data structure and calling CopyBits(). 
/* 

PLOTSICN - Draw the sicnNUMth small icon of sicn іп sicnRect 
of window. 

x 

PlotSICN Csicn, sicnRect, sicnNum, window) 

Handle sicn; 

Rect *sicnRect; 

short sicnNum; 

WindowPtr window; 


BitMap sicnBits; 
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/* Set up the bit map */ 

sicnBits.rowBytes = 2; 

SetRect(&sicnBits.bounds,8,9, 16, 16); 

sicnBits.baseAddr = *sicn + CsicnNum * 32); 

/* Blit the SICN */ 

CoptBits(&sicnBits,&window->portBits, 
&sicnBits.bounds, sicnRect, srcCopy, NIL); 


Note that we’re passing a dereferenced handle (*sicn). But 
according to Professor Mac (Steve Brecher), there’s no need to 
lock the handle, since CopyBits() won't alter the heap configu- 
ration unless a picture or region is being recorded. 

Colorizing Logos 
David Dunham 
Goleta, CA | 

With the advent of the Macintosh II, programs can use color. 
Doing so effectively and correctly isn't easy (both technically 
and from a user interface standpoint). But it’s easy to add a little 
spice to a program by colorizing the logo in its "about" dialog. 

This note assumes that logos are normally PICT items in a 
dialog, and explains how to make them appear in color on a 
Macintosh II. 

The simplest way to create color logos is to use SuperPaint. 
Copy a bitmap to the object layer, activate the color palette, and 
give the bitmap color. If you want to use different colors, you'll 
have to use multiple bitmaps. Note that SuperPaint's color 
names are misleading. What it calls "orange" displays on the 
Mac II screen as red. Since you have to run SuperPaint in 1-bit 
color, the easiest way to see what your graphic really looks like 
is to copy it into a desk accessory like Ácta or Scrapbook and use 
Control Panel to turn color on. 

If you don’t own SuperPaint, you can edit a ‘PICT’ resource 
with ResEdit. The fgColor opcode is OE, and it takes a longword 
of color data (see Tech Note 21). 

An advantage of this technique is that you can use it even 
without owning a Macintosh II. I gave Acta 1.2 a color logo even 
though it was released before the Macintosh II was introduced. 
I was able to check my work by printing with an ImageWriter II 
and a color ribbon. Also, this technique takes no programming, 
you can color arbitrary shapes, and it's compatible with all 
machines. The disadvantage is that you're limited to the 6 colors 
Fig. 1 A Mini-disk icon from the system file 
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(not counting black and white) supported by the original Quick- 
Draw. 

If you want to use colors which aren't black, white, or the 
additive and subtractive primaries, you've got to use Color 
QuickDraw. But at the time I'm writing this, there are no 
programs which create Color QuickDraw pictures. (Even if there 
were, these pictures can't be used on machines which aren't 
running System 4.1 or later. The structure of a version 2 picture 
prevents it from crashing a machine without ColorQuickDraw or 
the patches, but also means the picture will come outblank.) And 
pictures are played back in their original colors— you can't use 
an old ‘PICT’ and just call RGBForeColor and then DrawPicture. 

I use a technique similar to the way you dim text— draw it, 
then Bic a grey pattern over it. In color, use the new max transfer 
mode. This replaces the destination color with a color whose 
individual RGB values are the larger of the source and destina- 
tion colors’ RGB values. Since the original art is in black, and the 
dialog backround is white, this simply replaces all black pixels 
with the color we want (the RGB values for a black pixel are all 
0, so our color is used; the RGB values for white are all 65535, 
so our color is ignored). 

There is a catch— this only works if the dialog is a color 
window (i.e. has a color grafPort). GetNewDialog creates color 
windows if there 's a 'dctb' resource with the same ID as the 
"DLOG"' resource. The easiest way to create а ‘dctb’ it to use 
ResEdit to copy the one from the Control Panel desk accessory 
and change its ID. 

Note that in a 1-bit deep bitmap, max maps to Bic. Painting 
in this mode would erase the picture, so we don't do anything. 
(I’m assuming that the dialog doesn't extend over different 
screens; if it did, the picture could be colorized on one screen and 
erased on another.) 

I used this technique to give Findswell a color logo that 
matched the logo on the box. The C routine below is the one I 
used. It's hardcoded to Findswell's color, but you could pass the 


color as an argument. 
define тах СЗТ) 


"define RGBBlack CCRGBColor *20xc10) 
"define КОМ85 C*Cint %20х28е) 
/* 


COLORIZE - change the color of an item in а 
(color) dialog 
x 


void colorize(dialog, item) DialogPtr dialog; int item; 


int type; 
Handle handle; 
GDHandle gh; 
PixMapHandle pm; 
Rect box; 


RGBColor colour; 


If C!CROM85 & 0х4000)) ( /* Mac II ROMs? */ 
/* Figure out screen depth of our dialog */ 
gh=GetMaxDevice(&CCDialogPeek )dialog)-> 
window .port.por tRect); 
pm=(*gh)->gdPMap; /% Device’s PixMap */ 
if CC*pm)-»pixelSize > 1) ( /* Enough pixels */ 
/* Choose FindSwell'sgolden-brown */ 
colour .red=39921; 
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colour .green=26421; 
colour .blue=@; 
RGBForeColor(&colour); 
PenMode(max); 
GetDItem(dialog, item, &type, &handle, &box); 
PaintRect(&box); /* Colorize */ 
RGBForeColor(RGBBlack); /* default color */ 
PenNormal(); /% Restore default pen */ 


/* Set the color */ 


One disadvantage of this technique is that youcan see the logo 
being drawn in black, then painted in brown. The operation is 
pretty quick, though, and doesn’t require much code. 

What if you don’t want to color an entire picture? You can 
define a userItem, and pass its item number to colorize. This lets 
you color any rectangular area. To color an arbitrary shape, you 
can define a bitmap and use CopyMask (CopyMask is not 
available with 64K ROMs, but we’re not colorizing in that 
situation). Icons are probably the easiest bitmaps to work with. 
The routine below will plot the black bits of an icon in the current 
color; white bits are unchanged. 

/* 


PAINT_ICON - Draw transparent icon in current color 
*/ 


paint iconCicon, box) Handle icon; Rect *box; 


BitMap iconBits; 
GrefPtr X thePort; 


GetPort(&thePort); /% Get current grafPort */ 


/* Set up the bit map */ 
iconBits.rowBytes=4; 
SetRect(&iconBits.bounds, 0,0,32,32); 
iconBits.baseAddr=(char *) (*icon); 
/* Blit the icon */ 
CopyMask(&iconBits,  &iconBits, 


&thePort-»portBits, 
&iconBits.bounds, &iconBits.bounds, box); 


ModalDialog Filter Procs from MS FORTRAN 
Jeff E. Mandel, MD MS 
New Orleans, LA 

When writing code in MS FORTRAN, it is occasionally 
necessary to have a pointer to a piece of code to pass to a toolbox 
call — a proc pointer. Absoft has provided a glue routine called 
ctlprc to perform this function. Ctlprc has a limitation in that it 
does not return anything on the stack, which is necessary for 
implementing a filter proc for ModalDialog. An assembly 
language glue routine for this is described herein. 

ModalDialog filter procs are called each time ModalDialog 
gets an event from GetNextEvent (note that the event mask 
excludes disk insert and application events). It passes a pointer 
to the FrontWindow, and two VARs; the EventRecord and the 
ItemHit. Note that VARs are longword addresses to the data 
structures, which is exactly how FORTRAN passes calling 
arguments. ModalDialog expects the filter proc to return a 
Boolean result; True if ModalDialog should process the event, 
and False if the filter proc has done so already. A Boolean result 
should be passed as a word on the stack above the calling 
arguments, and this is where ModalDialog expects to find it. 
FORTRAN passes calling arguments as long word addresses, 
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and ctlprc restores the stack on return from the called procedure. 
Function results are passed register DO, and ctlprc trashes this 
register. Thus, we must write some assembly code to fix this if 
we want to write our filter proc in FORTRAN. The following 
MDS code does just that. 


XDEF xfilt 
INCLUDE MacTraps.D 


INCLUDE SysEqu.D 
INCLUDE ToolEqu.D 
INCLUDE QuickEqu.D 


; Xfilt is the initialization code. It stores the 
; address of the FORTRAN subroutine returned from 

; etlpre and returns а proc pointer which can be 
J 


; passed to ModalDialog. 


MOVEM.L A0-A1,-CSP2; Save registers 

MOVE.L 16(5Р),АЙ ; calling FORTRAN passes ptr 
LEA ѕегуісе,А1 ; to filter subroutine 
MOVE.L САЙ), СА1) ; which we store locally 


LEA action,A® ; glue procedure address is 
MOVE.L 12¢SP),A1 ; returned to FORTRAN on the 
MOVE.L A@,CA1) ; stack 


MOVEM.L CSP2*,A0-A1; Registers restored 


; Action is the proc which gets called by ModalDialog. 
; It massages the stack after FORTRAN finishes with it 
; so that а Boolean result can be returned to 
; ModalDialog. 


action: 
MOVEM.L A1/D@,-CSP); Save registers 
PEA result ; Pass FORTRAN an address to 
; store the BOOLEAN result 


; Clone the stack 
MOVE.L 24(SP),-(SP) ; Dg.ptr 
MOVE.L 24(5Р),-(ӨР) ;Event record 
MOVE.L 24(5Р),-(ӨР) ; ItemHit 


MOVE.L service, Al; load ptr to FORTRAN 
JSR (A1) ; routine and call it 


MOVE.W result,24(SP); get function result and 
; place on stack where 
;ModalDialog expects it 

MOVEM.L (ӨР2%,А1/00; restore registers 


; Fix the stack so that we can RTS 
MOVE.L (SP)+,8CSP); move return address 


ADD.L %88,5Р ; fix stack pointer 
RTS 

; Declare some local storage 

service DC.L 

result DC.W 0 
end 


The following MDS link file will make a file that the FOR- 
TRAN linker can deal with: 


; File xfilt.Link 


/Data 
/Type "00007 ‘8200’ 


Ixf ilt 
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[Output xfilt.sub 
[ 


xfilt 


$ 
Next, we need to set up pointers in the main program: 


PROGRAM WHIZ BANG 
implicit none 


integer ctlprc, my.filter, filter. 1, my filter ptr 
external ctlprc, my filter 


filter 1-ctilprc(my filter, 16) !Four long word 
! of arguments 
call xfiltCfilter_1, my_filter_ptr) 


Note that the call to ctlpre should be performed any state- 
ments which allocate memory. The FORTRAN filter routine, 
my_filter should be appended to the main program. This simple 
filter routine handle carriage returns in a non-standard way. 


subroutine my_filter Cargptr) 
implicit none IDeclare all variables. 


integer toolbx 
integer Dg.ptr, ItemHit ptr, ev.ptr, argptr 
integer result ptr 


integer*1 eventrecord( 16) 
integer*2 what 
integer*4 when 
integer*2 where(2) 


loverlying structure 

Itype of event: 

Itime of event in 60ths sec 

Imouse location in global 

I coordinates 

integer*2 modifiers !state of mouse button and 
Imodif ier keys: 

integer*4 message lextra event information: 

equivalence Ceventrecord(C12,what) 

equivalence Ceventrecord(3), message) 

equivalence Ceventrecord(7), when) 

equivalence Ceventrecord(11), whereC1)) 

equivalence Ceventrecord(15), modifiers) 


integer aDef Item, editField 
parameter CaDefItem=Z’A8', editField=Z’A4‘) 


result ptrslongCergptr* 12) 
Dg_ptr=longCargptr +8) 
ev_ptr=longCargptr+4) 
ItemHi t_ptr=longCargptr 2 


do Ci=1, 16) 
eventrecord(i) = byteCev_ptrti-1) 
repeat 


if (what .eq. 3) then !keydown 

if user hits return or enter key, check the default 
item number. If it is zero, then return with 
ItemHit as the active edit text field. If the 
default item is nonzero, return it as the ItemHit. 


€» €» О C 


char_code=message .and. 7”000000ҒҒ” 
if Cchar_code .eq. 13 .or. char_code .eq. 3) then 
if Cword(Dg_ptr + aDefItem) .eq. 8) then 
ItemHi t=word(Dg_ptrteditField)+! 
handle_event=.false. 
else 
I temHi t=word(Dg_ptr+aDef Item) 
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handle_event=.false. 
end if 
else 
handle_event=. true. 
end if 
end if 
if Chandle.event) then 


word(Cresult.ptr)-22z'0' 
else 

word(result.ptr)-z'FFFF' 

wordCItemHit ptr2-ItemHit 
end if 


return 
end 
Finally, we call ModalDialog with our proc pointer: 


call toolbxC MODALDIALOG, my filter ptr, ItemHit) 


Note that if you are using this scheme to allow your program 
to do backround processing while you are waiting for the user to 
choose to do something from a modal dialog box or alert, this 
code should execute when a null event (what=0) is detected, and 
should pass the vent to ModalDialog (handle event - .true.) if 
you want the text insertion point to blink. Also, if you want to 
handle your own application events, call GetNextEvent in the 
filter proc with EventMask = Z'F000' (so it doesn't steal dialog 
events). 

Please note that this article is not an epistle for FORTRAN as 
aprogramming language, just some help for those of us who have 
too much invested in FORTRAN to move to Pascal or C. 

32K Limit & PMMU 
Daniel Weikert 

I'm now in my second year of Mac ownership and this brings 
about the time to decide which Mac mag's to re-subscribe to and 
whichtoletgo. MacTutor was neveron the let go list, so enclosed 
you'll find my renewal form and check. 

I have read a lot of discussion about the “32K limit” in certain 
compilers lately. I have no connection with any of the compiler 
authors in question so I can't say definitely why this limit was 
imposed, but one explanation that I haven't seen yet is for future 
compatibility with systems using Motorola's 68851 PMMU. 
The largest page size this chip will reserve is 32K bytes, There- 
fore to insure that software will run on the next generation 
machines which will no doubt incorporate this chip, maybe it 
isn't such a bad idea to limit yourself to 32K segments. 

Lazy Man's Color Comments 
Scott Boyd 
Bryan, TX 

Just a few comments on the article "Lazy Man's Color" (July 
'87, V3,7). 

First, it appears that the author has imposed a nonexistent 
limitation on the size of a handle. Handles can hold as large a 
piece of memory as the memory manager will allocate. His 
statement that “the size of a MacPaint bitmap is too large to store 
in 1 set (32K limit)" is unwarranted. I often allocate full paint 
bitmaps with no adverse effects. Indeed, allocating bitmaps two 
and three times the size of paint document is no problem on a 
MacPlus. 
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The artificial 32K limit made the code harder to read than it 
needed to be. 

Procedure DoSetup has the following two lines: 

Title := ‘Lazy Manes Color’; 

Title[9] := CHR(39); 

While that will work to create the string Lazy Man’s Color, 
the following statement works better: 

Title := ‘Lazy Man’’s Color’; 

One more thing, what’s with the alternating quotes and the 
hyphenated variable names in the source listings? Yuk. 

PopUp Pallettes Dangers 
Greg Marriott 
Bryan, TX 

I have recently heard from quite a few people about the 
unstated dangers in my pop-up article. 

In my article about pop-up pattern palettes, a paragraph was 
inadvertently left out makes a few disclaimers about the tech- 
niques used. In the article, I outline a method which fools the 
Window Manager into thinking that the pop-up window was 
never even there, so it doesn’t generate update events. Well, the 
way I chose to do that is, in general, not a very nice way to treat 
the Window Manager. I modify the windowRecord directly, an 
activity severely frowned upon by the guys who make “The 
Rules.” The way Apple sees it, anybody using such rude coding 
practices deserves what they get when the system changes. 
They’re probably right, but it still makes me mad that I have to 
resort to such “anti-social” behavior to get reasonable perform- 
ance. 

While I’m on my soapbox, I'd like to say a few words about 
a problem these techniques are going to have with future Apple 
products. Apple is commandeering the desktop. This means 
every program that affects the screen outside their windows is 
going to run into conflicts with other programs. Take my pop- 
ups, for example. Since I “steal” update events and put pixels 
back where I got them, I allow the pop-up to cover up anything 
on the screen. A rather drastic change in “The Rules” means that 
by the time the pop-up goes away, it could be putting old pixels 
back where new ones should be. As a result, one of the neat 
features I added to OverView becomes a problem. A small shift 
in philosophy has to take place to accommodate new technology. 
Instead of preventing update events and white flashes for every- 
body, we must now prevent update events and white flashes only 
for those who don't need them (our own windows). This can be 
accomplished in a few different ways; here is the way I chose to 
deal with the problem. Instead of emptying the pop-up window's 
region (structRgn, contRgn, and visRgn), subtract the parts of 
your window undemeath that you can get away with blasting. 
This can be done with successive calls to DiffRgn as follows, 
once for each of your windows: 

DiffRgn(WindowPeekCpopUp)^ .contRgn. 
WindowPeekConeOf YourW indows)^ . contRgn. 
WindowPeek(popUp )* . contRgn); 

Do the same for the strucRgn (I think you can ignore the 
visRgn), and the regions left in the pop-up window correspond 
exactly to the areas that don't belong to your application. When 
the pop-up is hidden, update events will be generated for any 
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windows covered by it (or at least what the Window Manager 
thinks is covered by it). This updated technique still modifies 
fields of a Window Record directly, so it still has a big red caution 
sign on it. The reason I won't just use HideWindow and 
ValidRgn (to “un-update” our windows) is because HideWin- 
dow erases the screen before allowing me to slap the pixels back 
into place. This is very side-effect that prompted the article in the 
first place! I wouldn't be forced to use such questionable 
techniques if more toolbox routines were provided for accessing 
low-level data structures. 
MS-Basic Wish List 
Michael Ching 
Honolulu, НІ 

In the April 1987 issue, we readers were asked to suggest 
features we would want implemented in future versions of MS- 
BASIC. 

Iimagine there would be many features people would want to 
be added to the language (most obviously a CASE statement for 
the interpreter). But in the months that I’ve been working with 
the MS-BASIC interpreter, my major complaints come not with 
the language itself, but rather with the editor. 

The most annoying problem is that in order to see long lines 
of code, one has to horizontally scroll thereby losing the context 
of the other lines. It would be nice if there were an option in the 
editor to have the text wrap around also. 

Secondly, when programming, I usually change a small 
section at a time and then print out that changed section to the 
printer. This is done by LLISTING from one label to another 
label. Unfortunately, this does not work with subprogram names. 
It would make senseif LLIST would also work with subprogram 
names. 

Finally, the editor is just plain slow. When inserting or 
deleting lines in aprogram of non-trivial size, it takes a noticeable 
amount of time for the change to "ripple" through the program. 

One thing that's missing in version 3.0 is the program to 
cross-reference variables and labels. You can get the old pro- 
gram to work if you save the program to 2.00 format, but 
somebody out there must have already modified it to work with 
3.0. 

What I really would like to see is a new version which would 
produce a complete cross reference. As it is now, the program 
merely counts the number of times each label and variable is 
referenced. I would want a version that would tell you where 
each variable appeared and where each label or subprogram 
name was GOSUBed or CALLed from. This might prove to be 
an interesting programming project. (Or perhaps such a product 
is available?) 

Likes Consulair C 
Clifford Story 
Murfreesboro, TN 

I got your letter in reply to my letter mentioning my prefer- 
ence for Consulair C over Lightspeed C. Here's why I said that 
Consulair is faster: 

First, I think there's little question that Consulair compiles 
faster than Lightspeed, in terms of lines per second or whatever. 
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Lightspeed gets its advantage from its integrated nature. Having 
compiled, it needn't launch another application to link the result; 
it goes straight to link. With that speed-up, its compile-and-link 
time is shorter than Consulair's and this is what people mean 
when they say Lightspeed is faster. I don't deny that Lightspeed 
compiles and links error-free code faster than Consulair. 

On the other hand, if your code contains errors, you never get 
to the link. Here again, Lightspeed has an apparent advantage 
because it has an integrated editor. Again, I don't deny that 
Lightspeed compiles and returns to edit code with a single error 
faster than Consulair. 

My code is rarely so clean, particularly when I am writing in 
C. With, say, five errors in the code, Lightspeed finds the first 
one— and dies. You have to repeat the cycle five times to get all 
the errors. With Consulair, once is usually sufficient— it will 
find errors, record them, and keep on going. Lightspeed forces 
you to remain at the desk during a compile and hold its hand. 
Consulair lets you play with the cat. 

Well, I wrote a 68000 disassembler in C, for the experience, 
and now I' m back to TML Pascal and MDS. That's what I really 
like. 

MPW Pascal Integer Divide Bug 
Scott Taggart 
San Jose, CA 

MPW has a bug concerning integer divides of SIGNED 
integers. When a signed integer (I think both 16 and 32 bit 
integers have the same problem) is divided by a CONSTANT 
that is a power of 2, the compiler optimizes this into this into a 
right shift. Unfortunately, the right shifting of a number to 
simulate a divide produces correct results ONLY if the number 
being divided was a POSITIVE number. If, however, the number 
being shifted is negative, the results MAY be incorrect. The 
result are sometimes correct depending on the value of the 
dividend. For example, the result of -10 div 4 when shifted yields 
-3, while -8 div 4 yields the correct result of -2. 

Note that this problem only occurs when the dividend is 
negative and the divisor is a constant and a power of 2. If the 
divisor is a variable, and that variable happens to contain a power 
of 2, the compiler must generate a call to do a ‘real’ divide 
because it does not know the value of the variable at run time. 

This problem did not exist with the Lisa Pascal compiler, as 
it ALWAYS called a library routine to perform a ‘real’ divide 
when the dividend was signed. 

A short term 'fix' to the problem is to place power of 2 


divisors into a variable. For example: 
ver x : integer; 


x := - 10; 


X :7 x div 4 ( yields bad value of -3 } 


While: 


ver x, v4 : integer; 


x := x div v4; ( yields correct result of -2 ) 
This bug was reported to Apple on 7/6/87. 
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Segmented DA's 
Tom Saxton, formerly 
University of Utah, 
Mathematics Dept. 

Ihave an idea for yet another article. I have been doing some 
consulting work with ALP Systems in SLC where we have 
managed to figure out how to write a segmented DA in Light- 
Speed C. There are several fairly subtle problems we have found 
and cured. Jon Nicponski and I are interested in writing up an 
article with a simple example program to illustrate the ideas. Are 
you interested? Finally, beginning next week I will be working 
for Microsoft as a "Program Design Engineer." [Would love to 
see your ideas on the Segmented DA, and while your at it, perhaps 
in your new calling at Microsoft, you can pass on some of 
MacTutor's complaints about the poor quality of Macintosh 
languages coming out of Microsoft. The MS Basic compiler has 
been a constant source of complaints in our letters department 
and the problems with Fortran are legend. These remain the only 
two Microsoft products after all this time, which in itself is an 
indication of how your new employer feels about the Mac. -Ed] 


Colorizing Programs 
Scott Berfield, 
Jack of All Trades 
Mindscape, Inc. 

In a recent issue (September 1987) I read with interest that 
SuperPaint can be used for colorizing logos for use in other 
programs. This is a technique with which I am familiar, but I 
don't use SuperPaint for it. I use Graphic Works 1.1 (of course, I 
get paid to say that!) for the same thing. GraphicWorks allows 
you to set fore and background colors for every one of 64 objects 
inapanel. That panelcan then be copied and pasted as a PICT that 
retains the color and transfer mode information. The one real 
advantage I can see to using GW 1.1 for this is that it runs in multi- 
bit mode, so you get to see and edit in color on the screen of the 
Mac II. Another interesting trick is to obtain a 256 color Pict from 
somewhere and paste it into GW 1.1 as a PICT — it will retain 
its colors — and then combine it with other elements to create 
your image. Then use that combined PICT to create your dialog. 
This works for color scans from a variety of sources, PixelPaint 
PICT images, and Image Studio grayscale images... it can give a 
program a dynamite look! 

Note: Early versions of GraphicWorks 1.1 may have prob- 
lems when run an a Mac II. If you run into such a problem, call 
Mindscape's customer service number (in the program's man- 
ual) and they will get you the newest version. This only affects 
Mac II users, so if you're using an SE or +, you should be fine. 

Finally, I notice that an awful lot of the letters and notes in 
your magazine are from people who are writing games for the 
Mac. I would like them to know that Mindscape is always 
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interested in looking at creative work. If you have a program you 
think is puvlishable, please don't hesitate to contact us! 


Attaching Icons To Applications 
Created Using MS Basic Compller 
David K. Wyatt 
Ithaca, NY 

There are probably better ways of accomplishing this particu- 
lar task than the method outlined here, but this method is 
relatively quick and simple. The only software tool required is 
Apple's ResEdit (the latest version I have is 1.0.1), though an 
Icon Editor can also assist in doing some of the work. The first 
thing to do is to remember to work on a copy of your application, 
preferably on a floppy. 

Open ResEdit, single-click on the name of your application, 
and choose Get Info from the File menu (or hit Ctrl-I). The first 
thing to do is to give the application a unique four-character 
Creator name— BODE in my case. The second thing to do on this 
window is to turn the Inited box off and the Bundle box on. Then 
click on the go-away box and, after answering positively when 
asked if you want to save the Info on your file, you will be back 
to the list of files on your disk. 

Next, double-click on the name of your application, and you 
will get a list of the current Resources installed in your applica- 
tion. This list is short, and in most cases will include only these: 
ACRL, ALRT, BASI, CODE, DITL, and STR. Hit Control-N (or 
select New from the Edit menu) and you will get the New Type 
Name: box. The way this particular element of ResEdit works is 
that you either choose an existing resource Type from the list on 
the left of the box, or type in anew resource type in the box in the 
upper right. 

Here, you want first to make a resource for your own, special 
application, giving it the Creator name you gave above. When 
you click the OK box (or hit Enter), you will be given a blank 
window. To get something to fill in, hit Control-I, and you will 
get the window. The only thing you want to do in this window 
is to change ID: to O. 

When you have done so, click the go-away box and you will 
be back to the listing of resources installed in your program— 
now including (in the example here) BODE. 

Again, the next thing to do is to hit Control-N to create a new 
resource. This time, use the scroll arrows to find ICN#, select it, 
and hit OK. You will then get a blank window, with no icons or 
editing template in it. You can do one of two things here. Either 
Paste into this window an icon you have created using an icon 
editor, or hit Control-N (for New) and get the icon editor frame. 

ResEdit will automatically assign a resource ID number to the 
icon you create here, and you should carefully note down its 
number such as 19328. When you have completed editing this 
icon, hit the go-away box and you will be returned to the ICN# 
window, with your new icon pictured there. Hit the go-away 
button again to return to the list of resources, which will now 
include ICN#. 

There are two other resources that the Mac needs in order to 
tie together the program and itsicon— a FREF and a BNDL. (We 
are proceeding in the order in which we are, because each step 
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requires an ID number generated in the previous step.) 

First, hit Control-N (New) again to signal that you are 
creating another new resource, and this time scroll down and 
choose FREF and click OK. You will get a window called 
"FREFS from «program name>.” Hit Control-N again, and you 
will get the FREF editor. 

You need to make sure that the File Type is APPL, and that 
the icon localID is 0. That's all. If they are not so identified, 
change them. Note down the FREF ID number, which in the case 
illustrated is 1948. Then hit the go-away button to get back to 
FREFS window, and again to get back to the list of resources, in 
which you will now see the resources you have added so far— 
BODE (your application Creator Type), ICN#, and FREF. 

You are now ready to bundle them all together in a package— 
view this next step as providing the machine with a way to know 
what goes with what. You need to create a BNDL resource. 

Again, hit Control-N and get the “New Type Name:” box, 
select BNDL, and click OK. You will see a window titled 
"BNDLs from «program name»." Hit Control-N, and you will 
get the BNDL Editor window. 

At first you will only have the first part of this window, down 
to the first row of asterisks. Insert the OwnerName (BODE in our 
example) and make the owner ID 0. Then double-click on the 
row Of asterisks and you will get the next section of the window 
(you will have to use the scroll bars to see it all). Enter the 
information for the ICN# and FREF resources. Extend the 
portions between rows of hyphens by double clicking on the 
hyphens, and get another row of asterisks by double-clicking on 
the asterisks. Be sure to use 0 for localID in both cases. (I do not 
know why in both cases below there are blank sections.) 

There is one final bit of business left. Two of the resources in 
your application, as compiled by BASIC Compiler, are ge- 
neric— the same for every application unless otherwise changed. 
They have to do with what is shown when you click on the 
"About..." in the Apple menu. 

Double-click first on the ALRT resource, and you will be 
shown that two ALRT resource exist, with ID numbers 265 and 
266. Double-click on ALRT ID#266 and you will be shown the 
alert box showing "Created by BASCOM." This is arather bland 
message to give those who will use your application— and it's 
also, if you come to think aboutit, insulting to you! You probably 
want to tell the users who really "created" your application. 

Click on the "Created by BASCOM." You will find you can 
move the text around, and change the size and shape of the box. 
The same is true of the OK button. Double-click it to edit the text 
within, and you will get yet another editing window. The high- 
lighted text can be edited in the usual fashion, and you can make 
it extend for several lines. Click on the go-away box to return 
back to the previous level, and re-shape the text box and adjust 
its placement. Click go-away boxes to return to the resource list. 

Finally, you need to change the message that is displayed on 
the Apple menu. Double-click on STR (there is a single space 
following the R, which is a part of the name of that resource) and 
you will get the list of STRs in your application, Double-click on 
STR ID=256. You can simply edit “theStr” to say whatever you 
will. 
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When you are back to the desktop, hold down the Option and 
Command keys while re-inserting your disk into the machine. 
When asked if you want to rebuild the desktop, answer affirma- 
tively. Youare doing this in order to force Finder to take note of 
the fact that you have given your application a new icon. When 
the Finder has done its job and you open the disk, you will find 
your icon displayed on the desktop. /This is another area where 


Microsoft should have provided the means of linking with a 


resource file so that application icon information could be ac- 
complished in the normal manner. -Ed] 
LaserWriters Self-Destruct after One or Two Years! 
David E. Smith 
MacTutor 

A failure mode for the LaserWriter printer has been observed. 
After a year or more of use, the fuser roller under the green felt 
cover begins to disintigrate. This is caused by the rubbing of the 
rubber paper guides on the roller, leaving circular groves in the 
delicate silver finish of the fuserroller. The result of these groves, 
which line up perfectly with the rubber paper guides on the green 
felt roller covering, prevent toner on the paper from being fused 
properly to the paper as the paper passes over these roller 
imperfections. The groves also mar the paper surface, leaving a 
line on the paper. The failure mode seems to be the breakdown 
of the silver covering of the fuser roller, leaving it brittle and 
susceptible to the scratching of the surface by the paper guides. 
We know of two LaserWriters in this area which have this 
problem and suspect there may be others. If you know of a 
LaserWriter with this problem, please contact MacTutor. We do 
not as yet know what plans, if any, Apple has to fix this problem. 
Since it is mechanical, the fix will not be easy and probably will 
require returning the printer to Apple. We suggest all Laser- 
Writer owners get Apple Care immediately before this problem 
manifests itself as the fix could be quite costly. More next month 
after we find out what the Apple service organization proposes to 
solve this problem. 

A another failure mode that is not easily repaired is changes 
made to the EEPROM inside the LaserWriter. The printer appar- 
ently contains important start-up information in EEPROM inside 
the machine. It is possible to change this information by careless 
or deliberate postscript programming. If this is done, the post- 
script board must be completely replaced at a cost of $800, since 
the EEPROM is not replaceable. Apple, in their infinite wisdom, 
has designed a machine that through programming, can be 
destroyed and there is no way to re-program the EEPROM to re- 
set it’s parameters! Therefore, you should be very careful not to 
allow any “foreign” postscript code to be sent to your Laser- 
Writer. Imagine the howl if you could program your tv set to self- 
destruct without any way of re-setting it! However, a service 
technician told me that he thinks there is a secret method by which 
the EEPROM can either be re-programmed or erased so the 
LaserWriter can be made operative, since he claims an Apple 
Service Class instructor did just that, but apparently the secret has 
never been revealed. The reason Apple is so jealous of this bit of 
know-how is that the EEPROM contains the copy count and 
when it’s reset, the count goes back to zero. Still, it is inexcusable 
that a machine that costs $5,000 could be made useless by 


659 


careless programming. Hasen’t anybody on the LaserWriter 
design team ever heard of a reset button? 
IAZNotify Defeated 
Steve Halls 
Edmonton, Alberta 

Why do the Apple programs "ResEdit" and “MPW Shell” 
purposely defeat the “IAZNotify” mechanism (see tech note 
#64A) by clearing this ointer just before exit. For those of us who 
attempt to write memory resident tasks, this behaviour causes 
real problems. Generally speaking, a memory resident task may 
need a hook at the beginning of an application to open files and 
drivers, and a hook at the end of anpplication to close file/drivers 
and unpatch traps. If an IAZNotify proc that restores traps is by- 
passed, those patched traps will bomb in the next application. We 
need a consistent mechanism, and if Apple must subvert this one, 
cany they suggest another? Enough said? 

Is it true the MPW assembler creates incorrect machine code 
in some circumstances? [I am not aware of such a defect, 
however, it may be true. -Ed] 

Is APDA selling an updated version of MacinTalk that works 
on the Mac II? Does this mean Apple is supporting MacinTalk? 
[Yes and no. APDA has started shipping a Mac II version of 
MacinTalk, but no, Apple still refuses to acknowledge it' s exis- 
tance. -Ed] 

Absoft Fortran Compiler Update 
David E. Smith 

We have gotten several complaints from readers concerned 
about the Absoft 68020 Fortran compiler which they have been 
advertising in MacTutor. Apparently Absoft has not yet started 
shipping this product and a number of MacTutor readers who 
sent Absoft money are hopping mad about this. One reader has 
threatened a postal lawsuit over the issue. We suggest you contact 
Absoft directly to inquire on the status of the 68020 version of 
their Fortran product before you send any money. You might also 
want to be aware that a new MPW Fortran is currently going into 
beta test by another company, and that this product looks very 
hot! We hope to have more information on it in the next issue of 
MacTutor. The targeted release date for this new Fortran com- 
piler, which is said to be linkable to any MPW code, is the January 
MacWorld Expo. 

68020 News from Motorola 

One of our readers has kindly sent us a copy of the Motorola 
RoadRunner newsletter which contains some interesting tidbits 
on the future of the 68020 product line. "Estimates are that our 
68020 has upwards of 7046 of the worldwide installed base of 32- 
bit MPU's and 78% in engineering workstations. Our target for 
68020 shipments this year is 700,000, meaning that this device 
will reside in close to one million systems by year-end." 

The article also credits the Macintosh II by saying that 
momentum is building for the 32-bit MPU as the result of the 
maturing of many successful customer programs, "a number of 
which are in the lower end of the price spectrum, such as Apple's 
highly acclaimed Mac IL" Hmmm, lower end of the price 
spectrum, eh? I'll try to keep that in mind the next time I send in 
my $7,000 check for another Mac II and that's at developer 
prices! 
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A few words on the progress of the 68030 were also included. 
First silicon on the 68030 was reached in April and initial 
deliveries are on schedule for the fourth quarter of this year. The 
68030 provides "significantly higher performance" than the 
68020 at the same clock speed, while maintaining 100% software 
compatibility. The 68882 enhanced floating point processor is 
said to be on schedule for September samples. 
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More on Self-Destructing LaserWriters 
Rod Paine 
Bethesda, MD 

Just finished reading your “LaserWriters Self-destruct" let- 
ter. While you are correct in terms of the effect the damage fuser 
roller has on the printed output, I don't believe that the “rubber 
paper guides" are the cause of the problem, at all. I have two 
LaserWriters and have experienced the problem on one of them, 
requiring the replacement of the fuser assembly. The second one 
is maintained based on correcting what I found on the first and 
what appears to be a proper solution to the problem. 

The problem is that toner builds up on the back side of the 
“Fuser Separation Claws”, cooks and becomes hardened to a 
point where it begins to scratch away the fuser roller surface 
coating. It appears to only build up on the two center claws, the 
two outside claws don't seem suseptable to this build up of 
tonner. [Mine is on the outside claw! -Ed] I have since checked 
the two Canon PC-25 copiers that we have, which have almost 
identicle fuser assemblies and they exhibit the same problem. So 
does my own personal Canon PC-10 copier. 

I discussed this with the two Apple dealers that we purchased 
these LaserWriters from and made two phone calls to Apple at 
Cupertino. The dealers know nothing and Apple has never 
returned my calls. I called Simplified Copiers, the firm that sold 
us the canon PC-25 copiers, they also know nothing about this 
problem. Ihave looked at the fuser assembly in detail (Ireplaced 
the damaged one, a very simple task) and am confident this is the 
cause of the scratches. As the LaserWriter owner manual makes 
no mention of cleaning this area I think this is a serious problem. 

If you have any contacts at Apple who will address this 
problem, please include my name. In fact, if you want to look at 
the fuser assembly I replaced, I'll send it to you. In the meantime, 
keep the back side of the fuser separation claws clean and clean 
the fuser roller everyday, BEFORE you turn it on, including 
taking a look at the cleaning felt strip, that slides into the “green 
felt cover", look which is known as the “fuser upper cover”. I'm 
glad to see you bring this up, I was getting nowhere fast! 

Color Mac Not Finished 
Lawrence D'Oliveiro 
New Zealand 

The Mac II arrived at work about three months ago, and the 
draft copy of Inside Macintosh Vol.V not long after, After long 
hours wrestling with documentation that is inadequate, incom- 
plete, and often down right wrong, I managed to convert some 
grey-scale pictures we have on the Vax into colour QuickDraw 
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format. In the process, Itolearn how to create my own GDevice, 
in order to construct off-screen pix-maps. Tech note 44120 
doesn't really provide the answer, as I wanted to create PICTs 
with 256 colours in them, and my video card can only handle 16 
colours/grey scales at the moment. I expect lots of other people 
would have gone through this and already discovered what I 
know, but if not, one or two of my programs might be worth 
publishing. 

I eagerly typed in Steven Sheets' colour game of life in the 
september issue, and had some fun with that. There was a bug in 
DoColorClick (which lets you change the set of colours the 
program uses), which caused it to ignore any changes you 
specified — to fix this, just the following line: 

mycolors[il := ColorIt; 

Before the call to MakeRGBPat, after the begin. Apart from 
that (and the missing resource definitions), it's a pretty demon- 
stration, which I’ve shown lots of people. Thanks, Steven. 

Apple colour monitors are a little bit thinner on the ground 
than snow in December over here, but I managed to borrow an 
NEC MultiSync to try out for a couple of weeks. Picture quality 
isn't 100%— the picture narrower in the darker parts— though 
I expect the newly-announced MultiSync Plus should work 
better. 

I may be wrong, but it doesn't look like all the pieces of 
colour supply for the Mac II are in place yet. Some documenta- 
tion mentions a control panel module for changing the colour 
table, but I can find no such module anywhere. I wrote a quick- 
and-dirty utility for doing a similar thing (using the SetEntries 
colour Manager call), but my changes kept getting undone as 
soon as I exited the program. Eventually I dumped out the current 
colour table to a “clut” resource, pasted this into the System file, 
and put its resourse ID into the “scrn” resource, in the marked 
“CLUT rsrcID”. Now my program worked, even though I wasn't 
updating the clut resorce on disk! The colours reverted to those 
in the resource when I rebooted— I tested this by modifying the 
resource, it did have the expected effect. The only trouble was 
when I changed screen mode bit to 2 or 1 bit per pixel (the clut 
I created had 16 entries), and rebooted— the screen colours went 
all funny! Verdict: something is missing that Apple should be 
supplying. /The Pallette Manager? -Ed] 

The other thing I found is that MakeRGBPat, which approxi- 
mates a colour you specify by “ dithering" (making up a pattern 
using available coloursin the colour table in the right propor- 
tions), isn't very accurate. Quite frequently, I would ask it to 
approximate a colour which exactly matched an entry in the 
colour table, and it would mix in a bit of black instead of giving 
me a pure colour. Maybe in system 4.2... 

I hope this information is of use to others. After the silence 
of the Mac Plus, and the enhanced Fat Mac I was I was using 
before that, tha Mac II sounds like your in a jet plane. But then it 
performs like one! 

Apple Looking for a few Good Men 
David E. Smith 

At Apple's request, we have sent a letter to each of the 385 
past contributors of MacTutor to advise them of employment 
opportunities at Apple. If you have made a contribution or 
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requested an author's kit from MacTutor in the last three years, 
you should have received this letter. If you did not, then you are 
no longer in MacTutor's editorial computer for one reason or 
another and you may wish to contact me for a new author's kit. 
Apple has a number of technical management positions open and 
are looking for experienced Macintosh programmers such as 
those who write for Mactutor! For more information, contact Dan 
Cochran at Apple. 
Absoft Fortran Update 

In last month's MacTutor, we implied some problems with 
Absoft's new version of Fortran for the Macintosh II. We are 
happy to report that version 2.3 of MacFortran/020 is now 
shipping, having received our copy on 25 Sept 1987. Mr. Wood 
Lotz, President of Absoft also responded to the disgruntled 
customer and he is perfectly satisfied now. The manual has been 
re-written and now includes new information on the added 
features. The linker has been improved with a script builder 
utility that automates the link process. The linker is now a batch 
facility rather than a poorly designed interactive facility as it was 
in the past. In this respect it is more similar to the MDS and 
Consulair linker. The compiler includes options for selectively 
generating 68020 and 68881 instructions. It also continues to 
support the generation of assembly source code, a feature we 
think is invaluable and lament that other compiler makers have 
not supported this. Absoft's Fortran remains the only Macintosh 
compiler product that uses 32-bit offsets in it's addressing and 
does not use the segment manager. Thus there are no 32K code, 
segment or array limitations in MacFortran/020 as there are with 
virtually all MPW compilers. Now that the product is sold and 
supported directly by Absoft, we expect customer satisfaction to 
improve considerably over the previous Microsoft implementa- 
tion. Absoft can be contacted at (313) 853-0050. 

New MPW Fortran 

Language Systems Corp. of Herndon, VA has announced 
their development of a new MPW Fortran product. The product 
is scheduled to go into beta test in December. An information 
booth on the product will be available at the January Mac Expo 
in San Francisco. The product will feature 68020 and 68881 code 
options and will be linkable with all MPW compiler products. 
Variable types will include 68881 extended and complex preci- 
sion as well as a new type called STRING for dealing with Mac 
Pascal type strings with a length byte. Assembly source code 
output will also be available. Since this Fortran operates under 
MPW and uses the MPW Linker, it will be impacted by the 
segment manager limitations of other MPW products. However, 
arrays and common variables will not be restricted to 32K, 
according to a company spokesman. For more information, 
contact Language Systems at (703) 478-0181. 

Power Supply Woes Revealed 
Herbert M. Rosenthal 
Albuquerque, NM 

Chuck Rusch (June '87, p13) hit it right on the head with his 
articleon soldering imperfections in the early Macs!!! He has my 
undying gratitude for his comments and specifics which led me 
directly to the several intermittent, offending unsoldered 
connection(s) that had me rapping on the side of the Mac more 
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often than one should, to restore the video. I had installed an 
internal fan and varistor (both Radio Shack) a year ago, and am 
convinced that the fan kept my board from “smoldering.” 

One simply cannot see these cold joints without a magnifying 
glass, regardless of his hardware experience. Further, simply re- 
heating joints will not make a good connection; it is necessary to 
apply a wee bit of fresh, rosin solder to the joint as it is heated; the 
flux will cause the solder to flow properly. Finally, if you’ve 
braved the storm this far, clean up the work with a toothbrush 
dipped in alcohol; scrub till all the flux is cleaned up, dry the 
brush and scrub some more. 

MacApp Aids Complexity 
Charles Turner 
APO New York 

For some time now I have been incorporating some of the 
structure and flow concepts of MacApp, mostly gleaned from 
Kurt Schmucker's book Object- Oriented programming for the 
Macintosh, into my LightSpeed Pascal program in order to retain 
a reasonable amount of generality, modularity and maintaina- 
bilty as it grows increasingly complex. I looked to MacApp for 
inspiration since it was developed with objectives similar, at least 
in part, to my own and with a lot more talent and inspiration than 
I could put to that problem. 

Anyhow, it seems that much of the structure and flow in 
MacApp is different from the traditional generic program and 
may be generally useful. Also, fortunately, much of it can be 
implemented without the need for object programming. 

Since most of the programs you have published derive from 
the short sample in Inside Macintosh Vol .I and Chernicoff's 
Macintosh reaveled ,a sample of somthing a little different might 
beinteresting to readers who are battling the problems of increas- 
ing complexity. There are lots of ideas in MacApp just waiting 
for the light of presentation, assuming that Apple doesn't mind. 

Of course talk is cheap and writing is dear, but if you think the 
subject has merit and would send an author's kit, perhaps I could 
postpone the 127th improvement to my program and get some- 
thing together. And then maybe, just maybe, a moment of 
immortality on the cover of Mactutor. /Write away, author' s kit 
is 'in the mail' . -Ed] 

Camera Option for Cmd-Shift-3 
Neil Ticktin 
Encino, CA 

Response to August 1987 - Macintosh II Hierarchical Menus 
- Documenting programs (page 50). There is a desk accessory 
called “Camera” by Keith A. Esau. I believe that it is public 
domain or shareware. It takes a “snapshot” of the screen after a 
user specified amount of time. It also allows you to make the 
cursor invisible. The resulting snapshot is in Macpaint format or 
can be sent to the ImageWriter. I believe that you can get the desk 
Accessory from CompuServe or other information networks. 
[The Camera DA does not work on a Mac Il in color mode. In fact, 
none of the "paint" type programs workona Mac П set up for 256 
colors. This isone of the great needsfor the Macintosh; new paint 
programs that can work with color monitors. There is still no way 
to capture the screen image of a color display. -Ed] 

Resonse to August 1987 - Mousehole Report - “more woes... 
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from: mysteray". ComputerWare, of Palo Alto (CA 800-323- 
1133 or US 800-235-1155), is begging to sell kits to replace the 
Macitosh SE fan with a much quieter fan. I believe the kits sell 
for arround $40. I don'tknow if it will also solve the interference 
problems that I also have on my SE. Ihave not yet bought the fan 
, but I intend to. 

"No-Fluff Stores" 

David Kauffman 

Vancouver, B.C. 

In response to your APDAlog ad, I would like to commend 
what I consider to be Vancouver's best *no-fluff" computer 
store, Silicon-ections Books Ltd.. They stock an excellent 
selection of user-oriented and technical-oriented books on mi- 
crocomputers, networking, publishing as well as sections on 
UNIX, Artificial Intelligence and Computer Science. Thier staff 
are helpful without being pushy and know thier stock very well. 
Thier knowledge of Mac technical issues is a little lacking to be 
the kind of gurus you might be looking for, but Irecommend thier 
store as the best candidate in the Vancouver area. [Thank you. We 
encourage all Macintosh technical users to send in their "No- 
Fluff’ favorite so we can compile a list for the "rest of us“ 
technical types to patronize. -Ed] 

Major Havoc vs. Mr. Clean 
Jean-Michel Decombe 
Paris, France 

It's always been a pleasure to recieve the latest issue of Mac 
Tutor. Your articles are useful but I don't understand why VIP 
is great in your opinion. I don't know of any good programmer 
who would use it. OK, you have two types of programmers: 
Major Havoc & Mr. Clean. Major Havoc, of course, doesn't use 
VIP; he simply transfers garbage from his brain to the RAM via 
the keyboard; he doesn't care much about fancy graphics. And 
Mr. Clean can't see an overview of his project with VIP; he can't 
put remarks where he'd like to; what he sees on a full screen is 
about four lines of code; and scrolling isn't fun. Now take a non- 
programmer. He won'tlearn programming faster with VIP. OK, 
you have directaccess to the parameters of the ROM routines, but 
it doesn't help you a lot. You'll have to learn how these routines 
Work, when they should be used, the side effects, and so on. I 
think Zippy is right: If I use VIP, do I have to give my project 
manager ten per cent?? So, I'dlike to know who should use VIP. 
Thank you for your answer, if any. 

I send you a very very small but very very handy trick if you 
frequently use any debugger. Aldo Reset made it for me: 

1)Jump to ResEdit, to open your System file, then open the 
FKEY resources. 

2) Choose New from the file menu; a window appears with 
blinking caret. Type the following hex string in: 

487A 0006 ABFF 4E75 1842 6162 7920 4569 6E73 2773 
2044 6562 6765 72 

4) Close the window and choose Get Info from the File menu. 
Change the type to BED (Baby Einstein's Debugger), the ID to 
anumber between 5 and 9, or 0, Which isn't the ID of any of other 
FKEYs, then set the Purgeable attribute. 

5) Close and save everything, then return to shell. 

Now, you can access the debugger installed by typing Com- 
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mand-Shift-ID, where ID is the ID of the BED FKEY. In the hex 
string, the underlined part is a Pascal string that you can change 
whatever you want. Just remember the first byte is the length. 
You can of course use a smaller or longer string, up to 255 bytes. 
Have fun! 

[I think VIP is fun! VIP procedures replace ten to 20 ROM 
routines with a single VIP command, which greatly reduces the 
code needed to generate a Mac program. Printing text from a 
window is a single procedure call in VIP. Compared with a 
compiled language like Pascal, the same effect would take 
severalpages of complex print manager code. All five translators 
for LS C, MPW C, MPW Pascal, Turbo Pascal and LS Pascal are 
now completed. Mainstay translated and compiled a single VIP 
program in all five languages and found out the MPW transla- 
tions were twice as fast as the Turbo and LS products. More on 
this work will be available next month. VIP may be the ideal 
prototyping language with the added benefit that the design can 
be turned directly into code. I invite others to comment on the 
suitability of using VIP for software development. -Ed] 

ZBASIC Comments & Shift Mod Patch 
Steve Millman 
Plandome, NY 

Your September issue lived up to its usual fine standards, and 
as always, taught me a lot of things I wanted to know. I do have 
two comments/questions, however. 

1. David Kelly's Basic School article shows how to write a 
full event loop in ZBASIC, which is useful. Howoever, the 
expressed purpose was to allow the program to check for a 
specific type of event, such as a disk insertion, that ZBASIC 
doesn't handle. The full event loop seems like a lot of work (and 
seriously reduces the benifits of using BASIC in the first place). 
Why doesn't something like the following work in place of the 
usual ZBASIC empty loop: 


“loop”: 
IF FN EventAvail(p, disk event mask) GOSUB 


*hendleit^: GOTO loop 


MENU ON : MOUSE ON: DIALOG ON 
REM 
MENU OFF: MOUSE OFF: DIALOG OFF 
GOTO “loop” 

*handleit^: 


ans=FN GetNextEvent(p, disk event mask) 

whatever action program is supposed to take 
RETURN 

The only problem I can see with this type of workaround is if 
the disk insertion event is posted at a time no other events are on 
the queue and between the line turning ZBASIC event trapping 
on and off (so that ZBASIC reads the event and discards it). I 
can’t imagine this will happen very often. 

2. The ShiftMod note, which was incredibly useful to me 
(because I didn’t know how to do an epilogue patch) fails to note 
that the program will not affect the behavior of DA’s—If you 
type a key with the caps lock and shift down when the fwindow 
is a DA, the result will will be a capital letter. No, I didn't really 
try ShiftMod, but I used a modified version to imitate Loftus 
Becker’s ToggleKeys on the new system. (ToggleKeys, which 
is probably not much use to programmers is virtually a necessity 
for people like me who do a lot of normal style typing. It makes 
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the shifted comma and period keys print as comma and period 
rather than “<“ and “>”. It modifies the key mapping. When 
Apple changed the KeyTrans vectors in System 4.x, it made 
ToggleKeys— and its big brother Keymap— unusable.) Since 
I don’t understand the KeyTrans stuff at all (despite an otherwise 
excellent article in a prior issue), changing the characters re- 
turned by GetNextEvent seemed best. It works fine as long as 
you are typing in an application. In a DA, though, the INIT is 
ignored. 

Why? After a lot of searching through Inside Macintosh, I 
discovered when a DA window is frontmost, the DA KeyDown 
events are sent directly to the DA by GetNextEvent— by the time 
ShiftMod gets to look at the returned event, the DA has already 
used it. 

One, not quite perfect solution that I tried, is to use a patch 
GetNextEvent with a prologue instead of the top of the event 
queue and if that event is a Keydown or Autokey event, it 
modifies the character code. 

This works fine for keydown events and most of the time for 
auto events. Howeveran occasional autokey event doesn’t seem 
to get the message. I don’t know why and I’d love an explanation 
for it if you have one. (I guess that sometimes GetNextEvent is 
pulling the autokey from further down in the stack. I could 
understand this if GetNextEvent where being called with a mask 
EveryEvent, but the problem doesn’t seem to be limited to only 
one application.) 

Animated BitMaps 

My bad typing led me into a closer look at the code in the 
Animated BitMaps article. In function InitDrag, Scott violates 
one of the most clearly stated prohibitions inside the Macin- 
tosh— he directly modifies the visRgn of a grafPort with: 

RectRgn( thePor t* . visRgn, thePort* .cl ipRgn** .rgnBBox); 

“The visRgn... is reserved for use by Macintosh system 
software, and should be treated as read-only. The default visRgn 
is set to the portRect.”— Quickdraw С.А [I cannot find this 
reference, although the IM 1-149 does state that the programmer 
“normally should not modify the visRgn” -Ed] 

He had plenty of incentive to do so— DrawPicture respects 
the visRgn and will refuse to draw any bits in your off screen 
bitMap that are outside of the visRgn. 

I finally found a way to stay legal but also to draw success- 
fully: just before using DrawPicture in the NewDraggable proce- 
dure, set the origin of the off screen bit map to the top left corner 
of the picture’s pictureframe. Then, set the port bits. SetOrigin 
has the nice property of adjusting the visRgn, legally, as a side 
benifit. 

Replace this code in NewDraggable: 

OpenRgn; 

HlockChandleCtheP icture2); 

DrewP icture(thePicture, thePicture**,picFrame); 
HUnlock (Hndle( thePicture)); 

CloseRgn( thePictureRgn); 

with this: 


MoveHHi CHandleCtheP icture2); 
HlockCHandleCtheP icture22; 
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with thePicture^^.picFreme do 
SetOriginCleft, top); 

SetPor tBitsCpictureBits); 

OpenRgn; 

DrewPictureCthePicture, thePicture^^.picFrame); 

HUn lock CHandle( thePicture)); 

CloseRgn( thePictureRgn); 


Naturally, you should remove the offending RectRgn state- 
ment that illegally modified visR gn іп InitDrag. Effective anima- 
tion is delightful; thanks Scott. 

Raving on Mac 
Gary Odom 
(The Midnight Hacker) 
Tullahoma, TN 

Time to blow the horn on some software. 

Just got QUED/M, the new macro editor from Paragon 
concepts. It is excellent, and ca onsiderable improvement on the 
earlier QUED. The macro facility is real sweet, if not yet 
complete (Paragon is working on adding more pizzaz, though it’s 
more than powerful enough for what I need). There is a powerful 
built-in grep (for those who don’t grok UNIX, that’s a multiple 
file search utility). My only beef is the use of “non-standard” 
menu-keys (‘w’ for save instead of ‘s’, forexample). It took me 
about thirty minutes of hacking in ResEdit to adjust the menu 
keys to taste. for all the time we devlopers spend munching 
ASCII, we deserve a quality editor. This is it. 

I keep on seeing advertisements for Inside Mac reference 
tools. Well, Bernard Gallet has written a wonderful DA with 
Inside Mac Vols.1-4 contained therein. Extremely convenient, 
and for it’s $10 suggested shareware price, it’s a prize. 

Tooting my own horn for a paragraph: why spend $25 for a 
Mandelbrot set generator when you can get one heckofa Mandel- 
brot zoom lens for free (hmm, the cost of a download)?! Man- 
delZoom 3.0 is available on GEnie (Education library, author G. 
Odom). It is REAL slow because it is inSANE, but that’s only if 
you want to zoom down to 1 to the 10-billionth. The program 
allows one to save data plots for later retrieval, and you can use 
good ole “point n’ click” to select new pictures. If you’re into 
Mbrot, you should definetly check this one out. 

I leave with a kick to the tush to you C code puppies out there 
(and I’m referring to some I’ve seen in MacTutor). The braces 
should line up, guys and gals, as should everything else. 
struck goodbrace struct badstyle ( 
short on_looks; 

long on.nonsence; 


short eye; 
short read; 
); ); 

Isn't it obvious the way to go? With the braces vertically 
aligned, It's so easy to see where the code clauses begin and end, 
and verify proper code structure. Hey, get with the program! 

New MPW Book 
Charlie Nash 
Palo Alto, CA 

I would like to recommend to your readers an exceptional 
book find— "MPW and Assembly Language Progamming" by 
Scott Kronick, published by Howard Sams Co. What makes the 
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book stand out is that it actually teaches Macintosh assembly 
language. This contrasts with the myriad of "Inside Macintosh" 
clones that shoot for comprehensivness at the expense of expla- 
nation. 

Also, it's the first book I've seen that explains the basics of 
MPW. This is useful since the MPW docs run over 1200 pages. 
[Yes, this is a good introductory book on MPW and assembly; 
read it first before moving on to Dan Weston' s two volume set. It 
is written in the unique Kronick style; lots of interesting diver- 
sions along the way. Scott, Charly wants a free disk for this plub! 
-Ed] 

Mac vs PC for Fortran 
Keith Blerman 
Studio City, CA 

The author (September MacCad article) compares the Mac to 
the rest of the (computer) world as a FORTRAN development 
system. As much as I love my Mac, it is not an outstanding 
FORTRAN development system. Paul explains that the Mac cuts 
development time due to its quick compile and execute cycles. I 
did not have the author's code handy, so I used some of my own. 
The source code consisted of 4794 chars (Mac version, a few less 
for the PC, as there is no need to have a dummy common to 
reserve enough stack space). Test: Running a Mac+ with a 
LoDown 20 Mb disk, going from QUED/M to MS/FORTRAN, 
selecting the file for compilation and linking and creating a list 
file (to make the comparison fair, see below), then executing the 
code (which produces about 18,533 characters of output). In the 
other corner, my trusty PC-Tech X-16B (8 mhz-80186/8087 w/ 
IMb memory running PC-DOS 3.2; Seagate 225 HD (very slow 
for this machine-there is an onboard SCSI Capable of operation 
at4+Mb/s; unfortunately I am not utilizing it, so IO is at slow PC- 
bus speed) compilation from within the editor, and for contrast 
recompiling from the OS, followed by a LINK (including many 
more libraries than needed) and executed. 

MAC PC 

compile for syntax 345 145 

compile and execute 69s 43s 

The difference between my figures and the authors is not due 
to hardware differences, but due to the choice of PC compiler. 
The Lahey compiler generates code (if one turns off all the 
safeties) that runs within a few % of Microsoft's “highly 
optimizing" compiler, but compiles 10x faster. (Lahey simply 
generates good code, and makes no claim about optimizing - 
probably because Tom understands what a real optimizing 
compiler is expected to do, from his days creating Mainframe 
FORTRAN’S). 

In order to debug a Mac Program, I nearly always need the 
“listing” option, since the error messages are otherwise lost (or 
must be hand copied!). This is not necessary on the PC. LCS fully 
supports NAMELIST-a creature comfort that makes porting 
code to /from minicomputers and mainframes much easier. 

Also hidden is the fact that the LCS compiler produces much 
better error messages. Mismatched argument lists (checked at 
compile and at run time), flags unused variables, and much, 
much more. The LCS compiler is good enough that it merited 
the purchase of the PC clone! The time saved made the purchase 
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well worthwhile. The debugger is not as visual as the Mac, but 
Offers more features, and there is a code profiler which times by 
line or by subroutine, with 1msec resolution. There is an 80386 
version, which takes advantage of the larger memory space, and 
some of the new op-codes. 

The PC has many programmer oriented editors (none as good 
as QUED/M, but more than a dozen products which try hard). I 
use a rather simple one, which permits multiple windows, fair 
performance, and allows me to load and execute the compiler in 
its own window, Until Juggler is in my possession (and actually 
Works!) the Mac is worse off! MacFORTRAN certainly does not 
have an integrated editor, and I have yet to meet any users of 
DCM's FORTRAN. 

Paul makes many good points, and the Mac is a good choice 
(especially with a 68020/68881 combo). Aside from the com- 
piler itself, the Mac is a much better environment: QUED/M is 
vastly superior to any other editor, the ability to port FORTRAN 
Output (including plots) to reports and documentation, etc. 
makes it a very attractive choice. But, until MacFORTRAN's 
develop, the PC (O.K. a PC clone with a 20 mhz 80386/87 from 
A.I Architects) yields a more powerful, easier to develop number 
crunching code environment than the Mac. If one wants a 
consistent user interface and such... well the Mac wins hands 
down. Technical reports, and other documentation tasks, again 
the Mac. 

One last point: the Levco Mac is in the same price range as a 
minimal SUN, which has a much better FORTRAN environ- 
ment, much higher network performance, and (at present) more 
connectivity (nearly any UNIX system). Of course a minimal 
SUN doesn't include a hard disk, but if you have 3 or more 
people, the SUN fileserver yields better performance than a local 
Mac disk! [Apple has not paid enough attention to the need of 
making engineering quality compilers available on the Macin- 
tosh. However, we think this is changing fast and that the 
continued improvement of Absoft Fortran/020 and the arrival of 
MPW Fortran products will encourage more powerful number 
crunching compilers on the Mac II. -Ed] 

Mac Programmer Friendly? 
Dr. Robert A. Stine 
Philadelphia, PA 

What is important is the development environment that 
comes with the compiler, and here again there are two sides of the 
coin. I spend a lot more time debugging code rather than 
compiling and linking. If we look at C (and I think a lot of us do 
), then I think that Apple fans will be hard pressed to match the 
Codeview debugging environment of MS-C in the DOS world. 
Also, a very cheap C compiler for IBM's has a very nice 
debugging environment (MIX-C about $40), and the Datalight 
Optimizing C can do great things for slow code. 

In contrast, Lightspeed C, for example suggests using 
Macsbug—gag, I thought hex dumps were a thing of the past. 
Mac software is supposed to be user-friendly, but often seems to 
be very programmer-unfriendly. 

With that off my chest, I'll keep searching for a good 
Machintosh C implementation, and I hope that you will keep 
coming MacTutor issues as good as those I've come to expect. 
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[Macintosh is most decidely programmer un-friendly and has 
always been so. MacApp is Apple's response to this complaint. 
While I am being moved to MPW, I have never considered that 
a programmer -friendly environment in the Mac tradition. To 
date, only LS Pascal has a friendly source level debugging 
capability. Comments fellow hackers? -Ed] 
Larry's Copybits Code 

Fernando Salazar 

Wahsington, DC 

I want to thank Larry Rosenstein for his letter in the August 
1987 MacTutor (“BlockMove vs CopyBits"). I learned a lot from 
the letter - ГІЇ never be shy about using CopyBits again! I also 
wish to address some of his comments on my code. 

First, on hiding the curser, the code presented in my July issue 
letter does a HideCursor before each BlockMove, then a 
ShowCursor after. The same effect could be achieved with one 
ShowCursor at the end; but if the drawing that occurs in between 
takes a couple of ticks, the cursor appears to flicker. 

More important is what the OffScreenDraw procedure pre- 
sented in my July letter does. I use this procedure for re-drawing 
ascrolling window; the procedure makes an offscreen copy of the 
current port's bitmap, draws the scrolled version to it, then 
transfers the copy back to the screen. Even though bits outside 
the bitmap bounds may be copied to the temporary bitmap ( i.e. 
when bounds.right-bounds.left is less than rowbytes*8), they 
should be identical when copied back to the original bitmap, 
since drawing doesn't modify bits outside a grafport's 
portBits.bounds (IM v1, p155). If the bounds rectangle changes 
in between the first BlockMove and the second (as would happen 
if there wasacallto PortSize or MovePortTo) then all bets are off. 

It may be interresting to note that the program that uses this 
BlockMove method is my shareware application “CK” (avail- 
able on CompuServe), and that I have had reports of it being used 
on a Mac SE under System 4.1/Finder 5.5 with no problems. But 
Mr. Rosnstein's admonitions about code incompatabilities with 
new configurations are correct; CK certianly would not work on 
a Mac II. 

The only reason I used a BlockMove scheme in the first place 
was that I was unsure about the CopyBits 3.5K “limit”. CopyBits 
is the one of the most important QuickDraw calls, yet it seems to 
have a lot about it not publicly understood. In another example, 
Robert Denny's article "PICT Rotation with CopyBits" (Best of 
MacTutor Vol.I, p.210) revealed that CopyBits does not accu- 
rately scale to powers of 2. Why is that? Is there a way to predict 
how CopyBits will scale an image? Let me add my vote for a 
MacTutor article revealing the inside-story on CopyBits. 

Pagemaker & Down Loaded Fonts 
David E. Smith 

Pagemaker 2.0 has problems placing formatted MacWrite 
text files which contain down loaded laser fonts. Our favorite 
font, a mono-spaced laser font called thin Saratoga, often causes 
Pagemaker to respond with a dialog box claiming "using fonts 
not in the system file". It also has the disastrous effect of adding 
unwanted characters to our source code listings! We are trying 
to contact both the font maker and Aldus to ask about this. I 
suppose it's the old problem ..."go talk to the other guys!" 


665 


Vol. 3 No. 12 


MacTutor Editorial 
Multi-Finder Changes the Game 

The arrival of Multi-Finder changes the game for tool 
makers in the Macintosh world. When the Mac first came out, the 
emphasis was on one tool, one job. Consulair C and TML Pascal 
followed this design philosophy by making their compiler prod- 
ucts seperate tools. There was the editor tool, the compiler tool, 
the linker tool and so forth. Using switcher, these tools could be 
used very easily, switching back and forth between them. After 
a while, this mode of operation fell out of favor as new system 
enhancements made switcher unreliable. This led to the creation 
of the “all-in-one” environment of LS C and Pascal and the MPW 
shell. In these products, the tools are not seperate anymore, but 
integrated with the shell environment of the tool maker. These 
products have become very popular. This change in thinking has 
also affected application development. With Pagemaker, the 
tools for creating layouts were unbundled and seperate. You use 
a word processor to create text, a drawing program to create 
graphics, and a layout tool like Pagemaker for combining and 
creating layouts, using the files created by the other tools. Lately, 
however, there has been a movement to return to the large, 
integrated tool, that does both word processing, graphics and 
layout in one. Microsoft Word has expanded into page layout, 
FullWrite is supposed to rival Pagemaker, Scoop combines an 
editor, Paint and Draw program with it's layout capabilities. The 
result of this is that applications are bigger, more complicated and 
attempt to do all things for all people. This also makes them 
harder to debug, so that products like FullWrite and Scoop run 
over their ship dates by six months or more, and products like MS 
Word ship with bugs, causing a furor in the marketplace. 

In the new world created by Multi-Finder, these integrated 
environments are the exact opposite of what we want today. 
Multi-Finder gives the user the opportunity to create his own 
integrated working environment, by mixing and matching the 
tools he wants open at any one time. The integrated environments 
prevent this by either not working at all with Multi-Finder, or by 
being so big and massive as to make their use under Multi-Finder 
impossible without five megabytes of memory! 

The New Way of Tool Design 

To take full advantage of the new Multi-Finder way of doing 
things, tools should go back to the old adage "keep it simple, 
stupid! ". One tool for one job is our motto. And each tool should 
have a re-sizable, dragable window because Multi-Finder oper- 
ates best with normal windows. By clicking in the tool's window, 
that tool is immediately activated. The user can then open the 
tools he wants and arrange their windows on the screen or screens 
at his disposal. Also, tools should confine their controls to their 
own window, rather than blasting a control all over the screen (as 
in WriteNow's ruler). Normal, scrolling windows should be 
supported rather than fixed dialog boxes (as in Absoft's Fortran). 
Windows should be moveable rather than fixed (as in Apple's 
MacPaint). MacTutor encourages tool makers, both applications 
and programming products, to return to the idea of simple, 
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reliable, one purpose tool making, each tool in it’s own window. 

Lets concentrate on creating tool families thatcan share informa- 

tion easily and painlessly in the new Multi-Finder environment. 
Apple Defines the User Interface 

Apple has published a new book with Addison-Wesley that 
defines the user interface for Macintosh type computers. Because 
Apple is trying to port the Mac look and feel back to their Apple 
IIgs, the name of the book is Human Interface Guidelines: The 
Apple Desktop Interface. But in reality, this is a complete, single 
volume statement of how a Macintosh application should look 
and feel to the user. The book contains descriptions of the look 
and feel associated with such new topics as tear off menus, pop- 
up menus and hierarchical menus. What is not in the book, and 
is needed, is some idea on how the user interface the book 
describes can be implemented! (I’m thinking of writing a little 
booklet that would implement the user interface as Apple de- 
Scribes it as the Pascal shell example they left out!) Also missing 
is some discussion of the philosophy of tool design as I've 
indicated in this editorial, now that Multi-Finder allows multiple 
active tools to be sitting around on the desktop. Tools need to be 
designed in such a way that they can be confined by the user if he 
wants to push that tool off to the side of the screen somewhere. 
Also missing from the book is a discussion of tool design for 
Apple Share, and whatconstraints that environment puts on good 
programming practice. Perhaps we need a volume 2 of the Apple 
Desktop Interface: The Developer' s Perspective. Human Inter- 
face Guidelines is part of the Apple Technical Library Series 
from Addison-Wesley and should be available at the Mac World 
Expo in San Francisco. А must purchase for developers. 

Colorizer Fixes Color Problems 

Last month, we said you can't take a snapshot of the color 
screen. The Colorizer cDev from Palomar Software does 
allow you to capture a color screen and to save it as a color PICT. 
Eventually the graphics programs will get updated to work with 
color PICTS so this will be very useful. А new version, 1.1 isnow 
shipping and we recommend this product if you have a Mac II. 
Colorizer is a utility that adds colors to PICT compatible objects, 
allowing you to colorize MacDraw and other object oriented 
documents. See the mail order store in this issue, or contact them 
directly at (619) 727-3922. 

WriteNow Cures Pagemaker Problems with 
MacWrite Formatted Files 

As we have reported previously, the file filter in Pagemaker 
for MacWrite formatted files is buggy and often fails to place the 
file correctly. A dialog box comes up and says “you’ ve used fonts 
notin your system file" and so forth. This problem has been a pain 
for us since we normally use MacWrite as our "galley editor" 
tool. This gives me a chance to again rant and rave about how we 
need tools for specific jobs. 

In setting a magazine every month, you don't need or want 
the world's most comprehensive word processor. All that stuff 
just gets in your way. All you really need is a "galley editor". 
Such a product need only set the column width, leading, font, 
style and tabs for creating galley strips of editorial. But it must be 
fast, and bomb proof. Those strips are then typeset into magazine 
columns with a page layout program like Pagemaker. It is much 
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more efficent to keep these two tasks seperate. But Pagemaker 
has to be able to read a formatted file and version 2.0 can't do this 
reliably with MacWrite. So we have switched from MacWrite to 
WriteNow by T/Maker and NeXT, which apparently owns the 
copyright. All the editorial in MacTutor is now set up with 
WriteNow. A translator program allows MacWrite and Word 
files to be translated into formatted WriteNow files. (The trans- 
lator seems to have problems with Word 3.01, but you can save 
word files as MacWrite files, and the translator can convert those 
to WriteNow files.) 

WriteNow is an excellent example of what I mean by a 
"galley editor". It is simple, fast and obvious, like MacWrite, 
only better. It conforms to the new tool design philosophy by 
doing one thing well, like Filemaker. In fact, I think of it as the 
“Filemaker of word processors". (The only drawback is that it’s 
ruleris not confined to a window as it should be to be truly Multi- 
Finder friendly.) The ability to set the leading and check the 
spelling in WriteNow, and have that leading respected by Page- 
maker is what makes this tool so great for use with Pagemaker. 
As we have reported before, leading is a design goof in Page- 
maker that can wastea lof of time trying to re-set the results of the 
auto leading calculation. 

What I really like about WriteNow is that it follows the user 
interface in an obvious and simple way, unlike MS Word, which 
tries to go out of it’s way to be obnoxious. A simple example: you 
can set bold face type by pressing command-B, which should be 
obvious. But Pagemaker requires you to press shift-cmd-B, 
which is a physical impossibility for most normal people. I asked 
them why they did that and they said "because MS Word does!". 
Obviously, they never tested their own interface. Another ex- 
ample: fonts and style are easily changed, both globally and 
locally, without the pain of a messy dialog box like MS Word and 
Pagemaker require. And the built-in spell checking is so easy and 
fast that even I can use it! (No more letters on MacTutor's 
spelling problems!) 

So if your looking for a good galley editor for Pagemaker, 
take a took at WriteNow. It has multiple windows, spell check- 
ing, leading, and simplicity. Once more, it's file filter for Page- 
maker works correctly. If you write for MacTutor and have 
WriteNow, please submit articles as WriteNow files instead of 
MacWrite files, although we can easily convert them. Contact T/ 
Maker at (415) 962-0195. Current version shipping is 1.07, 
although I am using 1.0 on a Mac II with no problems. 

Big Arrays for LS Pascal? 
Noel Godlsmith 
Melbourne, Australia 

In the September issue of MacTutor, you published an article 
by Daryl Lovato on how he creates large arrays in TML Pascal 
(getting around the 32K limitation of the segment loader). I' ve 
tried everything andI can't get this example to work in LS Pascal. 
I’ve written to Think also to ask them about this. 

[The following unit will demonstrate how to create large 
arraysin LS Pascal following Lovato's example. LS is very picky 
about things, especially handles, but the big problem seems to be 
that the address returned for a locked handle is not the correct 
address at all, but includes the lock bit, which currently is stored 
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in the handle itself. To get the correct address, you have to clear 
the high order bit. In the SetElement routine, you need something 
like the following: 


MoveHHIChandle(mystuff 25; 
HLockChandle(mystuf f )); 
baseAddress := Ord4Cémystuff^^.dateStuff ); 
BitCir(@baseAddress, 0); (clear lock bit) 
cellAddr:*fakePtr(CbaseAddress*CelemNum*mustuf f ^^ .cellSize)); 
myPtr := fekePtrCelemPtr); 

FOR i := Ø TO mystuff^^.cellSize - 1D0 

cellAddr^[i)] := myPtr^[i]; 


This unit was set up to be used with the Pascal Code Tester 
that Jeff Fox wrote for us last month. If you add this unit to his 
program, and call GetBigArray in the test routine, then you can 
see the results of this unit. Note how the output is stuffed into the 
TextEdit record using TEInsert, where it will display with the 
next update event. Also, please be aware that the current version 
of LS Pascal is 1.11 and that this works (nearly) with the Mac II 
and provides the Volume 5 interfaces (still some bugs with the 
color video card turned on, switching context between the appl. 
and LS shell.) -Ed] 


UNIT errayStuff ; 
INTERFACE 
USES ROM85, TestGlobals; 


FUNCTION CreateNewArray(elemSize, upperBound :Longint):Handle; 
PROCEDURE SetElement(ary:Handle; elemNum: Longint; 

elemPtr :Ptr); 
FUNCTION GetElementCary:Handle; elemNum:Longint):Ptr; 
PROCEDURE GetBigArray; 


IMPLEMENTATION 


TYPE 

ArrayHd] = ^ArregPtr; 

ArrayPtr = “ArrayRec; 

ArrayRec = RECORD 
hiBound: integer; 
cellSize: Longint; 
dataStuff: integer; 
END; 


FUNCTION CreateNewArray; 


VAR 
tempHd] : ArreyHd]!; 
BEGIN 
tempHdl := ArrayHdlCNewHandleCOrd4CSizeOf CArrayRec)) - 2 + 
(Cupperbound + 1) * elemSize))); 
MoveHHI Chandle( tempHd1 2); 
HLockChendleCtempHd12); 
WITH tempHdl^^ DO 
BEGIN 
hiBound := upperBound; 
cellSize := elemSize; 
END; 
CreateNewArray := HandleCtempHdl2); 
HUnlockChandle(CtempHd!)); 
END; 


PROCEDURE SetE'ement; 


TYPE 
fakeary = PACKED ARRAYI 1.. 100001 OF signedbyte; 
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fekeptr = “fakeary; 


VAR 
baseAddress : LongInt; 
cellAddr, myPtr : fakePtr; 


i: integer; 
nystuff : ArrayHd!; 
BEGIN 


mystuff := ArrayHdlCary); 
MoveHHIChandleCmystuf f )); 
HLockChandle(Cmys tuff 25; 
IF CelemNum > Ø) AND CelemNum < mystuff^^.hibound) THEN 
BEGIN 
baseAddress := Ord4(8mystuff ^^ .dataStuff 2; 
BitClrCébeseAddress, 0); 
cellAddr := fakePtr(beseAddress*(elemNum х 
nystuff^^.cellSize2); 
myPtr := fekePtrCelemPtr); 
FOR i := 0 TO mystuff**.cellSize - 1 DO 
cellAddr^[i] := myPtr*Cil; 


END; 
HUn lock Chand]eCmystuf f 25; 
END; 


FUNCTION GetElement; 

VAR 
nystuff : ArrayHdl; 
beseAddress : LongInt; 
size : LongInt; 


BEGIN 
nystuff := ArreyHdlCery); 
MoveHHIChandle(Cnystuf f 25; 
HLockChendleCmystuf f 25; 
beseAddress := Ord4Cémystuff ^^ .deteStuf f 5; 
BitCirC@baseAddress, 0); 
size :* nystuff^^.cellSize; 
IF CelemNum > 0) AND CelemNum < nystuff^^.hibound) THEN 
GetElement := Pointer(baseAddress + CelemNum * size)); 
НО lock Chand1eCmystuf f >); 
END; 


PROCEDURE GetBigArray; 


TYPE 
BigPtr = “BigRec; 
BigRec = RECORD 
г: real; 
r2 : real; 
other : ARRAY(1..28] OF Longint; 
END; 


VAR 
myArray : handle; 
i : longint; 
Big : BigRec; 
VeluePtr : BigPtr; 
Value : real; 
strü, stri, str2 : str255; 
number : longint; 
BEGIN 
myArray := CreateNewArray(SizeOf(BigRec), 2000); 
strø := chr 13); 
stri := ‘Total Size of Record = '; 
number := SizeOf(BigRec); 
NumToStringCnumber, str2); 
stri := concet(str1, str2); 
TEInsertCpointerCORDC@str@) + 1), 1, JeffsText); 
TEInsert(pointerCORDCéstr1) + 1), length(stri1), JeffsText); 
stri := ‘Total Size of the array = '; 
number := GetHandleSizeCmyArray); 
NumToStringCnumber, str2); 
stri := concat(stri, str2); 


668 


TEInsert(pointerCORDC@strd) + 1), 1, JeffsText); 
TEInsertCpointerCORDC@stri) + 1), length(str 1), JeffsText); 
TEInsertCpointerCORDC@strd) + 1), 1, JeffsText) 
FOR i := 1 TO 2000 DO 
BEGIN 
Big.r := i / 1.8; 
SetElement(myArray, i, @Big); 
ValuePtr := BigPtr(GetElement(myArray, 1)); 
value := valuePtr^.r; 
stri := StringOf(value : 7 : 2); 
IF Сі > 500) AND Ci < 519) THEN 
BEGIN 
TEInsert(pointerCORDCestr0) + 1), 1, JeffsText); 
TEInsertCpointerCORDCéstr1) + 1), length(str1), 
JeffsText); 
END; 


END; 
DisposHendle(mgArray?; 
; 


END. 
LaserWriter EEPROM Behavlor 
Herb Weiner 
Portland, Oregon 

The following information relates to the item *LaserWriters 
Self-Destructafter One or Two Years!" on page 85 of the October 
MacTutor: It'sactually rather simple to "reset" the LaserWriter 
EEPROM, including the page counter: replacing the Version 
23.0 PostScript (original LaserWriter Version 1.0) ROMs with 
Version 38.0 PostScript (LaserWriter Plus or LaserWriter Ver- 
sion 2.0) ROMs or vice versa resets the EEPROM, including all 
non-volatile parameters, the page counter, and the printer serial 
number used by the protected versions of the Adobe download- 
able fonts. This is the reason that the page counter in early 
LaserWriters was reset to zero when they were upgraded to a 
LaserWriter Plus, but that the page counter in a newer Laser- 
Writer (with Version 38.0 PostScript) is not reset by this upgrade. 
(I don't know how the most recent version of PostScript be- 
haves.) 

The number at the lower left corner of the line graph on the 
startup page (1.00r2.0) indicates which version of the ROMs you 
have. If you have the old ROMs and your LaserWriter dies due 
to bad data in your EEPROM, perhaps you can persuade a 
sympathetic dealer to insert new ROMs long enough to power up 
the machine and reset the EEPROM. Alternatively, perhaps 
you'd rather spend the $800 on a LaserWriter Plus upgrade than 
a board swap! Note that this approach will work only if the 
problem with the EEPROM is bad data; if the EEPROM has 
physically gone bad, you can't cure it by reprogramming. Each 
location in an EEPROM can be written only a limited number of 
times before it goes bad, at which point the EEPROM would need 
to be replaced. (I suspect you could unsolder and replace the 
defective EEPROM, which the software might then reprogram 
upon power up, but have never investigated this suspicion.) 

I suspect it is somewhat unfair to blame Apple for the 
behavior of the EEPROM. PostScript is, after all, implemented 
by Adobe. It is my understanding that Adobe does not even 
provide source code to Apple. Perhaps I could expand this into 
an Article. (I am the author of the software for both Laser- 
Magic™ and МасЅсаптм) 

CDEV Notes 
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Robert Rossevelt 
New York, NY 


Thanks to your recent articles about the new control panel 
and ‘cdev’ files, Ihave been doing some experimenting and have 
discovered the following (possibly trivial) facts which have not, 
as far as I know, appeared in print. 

The control panel maintains a resource of type ‘clst’ in the 
System File. This resource contains information about the vari- 
ous cdev's in the System Folder. In particular, it contains a copy 
of each cdev's ICN# resource, which is distinct from the ICN# 
stored in the cdev’s file. This means that if you change the ICN# 
in the cdev file, the change doesn't show up when you open the 
control panel. 

However, if you hold down the command and option keys 
when opening the control panel, it will rebuild the ‘clst’ resource 
from scratch, thereby incorporating your icon changes. This 
procedure is distinct from holding Command-Option-Shift, 
which on some machines, resets the PRAM memory as well as 
rebuilding the ‘clst’. 

Remember that you'll also have to inform the DeskTop file 
about your changes if you want them to show up there. Note that 
the Chooser maintains a ‘clst’ of its own; presumably it serves the 
same purpose there as well. Thanks for an informative and useful 
magazine. 

Foreign View of Developers 
Charles Dyer 
Kingston, Jamaica 

One thing I really don’t like about shareware is when 
someone writes a shareware product and deliberately cripples it 
so that you have to send in the fee in order to get the ‘secret’ 
command to uncripple it, and then the author cashes your check 
but doesn’t bother to send you word one! Over the last two 
months, I’ve sent in two checks for useful shareware DA’s to 
people who did just that. Most people that I send shareware 
checks to break their necks getting back to me; these two don’t 
seem to be in any hurry. 

I note that you don’t seem particularly interested in Modula- 
2 any more. I plan on getting either Semper Modula-2 or TML 
Modula-2. Right now, I’m leaning strongly towards Semper, 
mostly because it'll work out cheaper for me and they bundle 
MPW in and ship for free. TML had the best shot, because 
Florida's a lot closer, and cheaper to get at, than Illinois, but they 
don’t seem to like to answer letters there. If they don’t respond 
to my letters when I’m offering them money, how will they 
respond later on if Ihave a problem, and after I’ ve given them my 
money? 

The same kind of thing afflicts hard drive manufacturers. 
I’ve written at least adozen and the only replies that I’ve received 
are from Jasmine, Warp Nie, and Relax. The others don’t seem 
to want my money. Maybe it’s my breath. Ah well. Enough 
moaning. I like your magazine. If you need someone to look at 
Modula-2 again, I’m available. /Developer' s, let's be kind to our 
overseas friends. And yes, we are interested in Modula-2, but 
TML never sent me a Modula-2 compiler either, so...-Ed] 

68010 Rumor Mil 
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Gary Odom 
Tullahoma, TN 

The October issue of MacTutor had a Mousehole report that 
the 68010chip, being pin-compatible with the 68000 could be put 
into a Mac (with no change in clock speed) and an “about 30%” 
speed increase would ensue. Scoth that rumor! A 30% speed 
increase is nothing to sneeze at, especially for a $50 chip you just 
slap in, but it just isn't $0, 

I have an early Moster Mac (one where they rip the 68000 
heart out, stick voodoo pins in the motherboard, and place the 
CPU on the "little beast"). I did some benchmarks with the 
68000, then popped in a 68010 and ran the same tests. I found no 
difference when loading a MacDraw document or doing a Mac 
C compile from RamDisk. The Mac C Sieve with register integer 
math showed only a 3.6% improvement, and the floating point 
tests actually were 596 slower! 

The 68010 has special "loop mode" instructions that are 
supposed to make for more effiecient processing in program loop 
situtations. This may account for the speed improvement in the 
register integer math benchmark. Why is the floating point 
slower? I don't know. Perhaps Sane? 

The Motorola 68000 Programer's Reference manual has 
some instruction execution times (in clock cycles) for both the 
68000 and 68010. The only significant difference is in the 
multiply and divide instructions, where the 68010 is about 30% 
faster in clock cycles. That may be how the rumor was started. 

Debugger Art Work 
Tim Hammett 
Auckland, New Zealand 

Put your Mac II into 256 colour mode, double click on the 
MacsBug 5.4 icon, and watch the show! /This little note intrigued 
me, so I tried it. MacsBug 5.4 displays a color fractal that 
increases in resolution the longer it runs.] 

Key Bug in System 4.1 fixed in 4.2 
Neville Smythe 
Canberra, Australla 

There is an error in one of the keyboard mapping resources 
in the System file 4.1, which is fixed in the new System file 4.2, 
which will not allow the characters A-tilde and O-tilde to be 
accessed from the keyboard. They are supposed to be obtained by 
pressing option-n А and option-n О respectively. The lower case 
characters work, as in 4 and 6, but the upper case do not under 
system 4.1. This is a real problem since in the Symbol font, 
option-n А and option-n О are the heavily used ‘contained in’ 
characters, c and c. As you can see, under System 4.2, this 
apparently has been fixed, since I am now able to display them. 

Custom Text Edit Project 
Clifford Story 
Murfreesboro, TN 

I'm working on a project to replace TextEdit with custom 
editing routines. Would you like an article on this subject? [Yes, 
we ve been after a TextEdit replacement for over a year! -Ed] 


Resource Roundup 


No Rez-ervations Needed! 


Facing the Future 


Since the last installment of Resource Roundup, there have 
been some major changes Mac-wise around here. 

As the tag line suggests, I have a new venue, in this case 
working full-time on the Macintosh in a company headed by 
yours truly. My Mac Plus showed up and the 512K is gone (sold, 
not stolen like the 128...). Now if only I had Alan Kay's 
Dynabook-style Mac, rumored due late in '88: in writing this at 
41,000 feet, my Mac is useless in the overhead compartment. 

However, itisn’t the prospect of swapping floppies 40 hours 
a week that prompted me to buy a hard disk. True, with the Ram 
Cache set at 384k, my Mac Plus with a Peak Systems hard disk 
seems at least 3x as fast as those 400k floppies. (The Peak Plus- 
30 was the cheapest 30mb I could find). However, I hate to agree 
with Steve Jobs — whose closed-architecture Mac design was 
admitted a failure by John Sculley — but the Plus30's fan is 
driving me bonkers. 

No, the reason W.S.T. emptied its bank account could be 
found on the 13 MPW floppies that had been lying around unused 
for a few weeks. I cheefully installed these floppies on the Peak 
Plus-30, tying up about 4 mb in the process. Which brings me to 
the subject of this month's Resource Roundup: 


MPW! 


Macintosh Programmer's Workshop is a complete develop- 
ment environment, and Apple’s long awaited “official” Macin- 
tosh-based development tool. Since the Lisa's are no longer 
made and, after the long-rumored slotted Mac is introduced next 
month, no one would want one anyway, Apple is nearing com- 
pletion of a two-year project to make Macintosh-based develop- 
ment available, both in-house and for outside developers. 

At this writing, Macintosh Programmer's Workshop is in 
release 1.0B2, meaning the second "beta" test release. It is 
rumored the complete MPW system will be in final release after 
the January Mac Expo, which should mean "by the time you read 
this!" Check with APDA on it's final status. 

MPW includes a shell, editor, various utilities, 68000/ 
68010/68020 assembler, C, Pascal and the MacApp extensible 
application. Encouragingly, the MPW object code format is 
straightforward, and the documentation describes it in enough 
detail for use by third-party compilers. (I've written and main- 
tained compilers with more cryptic documentation than that.) 

But of course, the focus here is on resources, and MPW has 
plenty to talk about. MPW comes with three new resource tools: 
Rez is a resource compiler; DeRez is a resource decompiler; 
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and RezDet performs rigorous consistency checks on resource 
forks. 

All three are implemented as MPW tools, which means 
these are invoked from within the MPW programming environ- 
ment with a UNIX-like line-oriented command. If you grok 
UNIX, Rez reads from standard input and writes to a resource 
fork. DeRez and RezDet read from a resource fork and write 
to standard output. Of course, the standard input and output of 
MPW apply to the data fork of any file they access, ignoring the 
resource fork, if any. Normally, standard output is the screen, and 
standard input is redirected from a file using the UNIX-like “<” 
notation. 

The Pascal compiler also includes the source to ResEqua1 
(It seems misspelled to me...) as a sample MPW tool for those 
who want to write their own. The tool compares the resources in 
two files, and reports the differences (if any) by resource type and 
number. As a tool, it has limited utility, but it illustrates how to 
use Resource Manager calls to read unknown resources, such as 
those added in a user-configurable application. 

MPW also includes ResEdit, the same one that has been 
pre-released in the various software supplements. MPW 1.0B2 
comes with 1.0A1 version of ResEdit (A for “Alpha”, or first- 
level field test); however, this is labeled 1.0D11 (D for “Devel- 
opment”, or internal testing), certainly not the latest version 
available at the release date, but perhaps the most stable. Re- 
sEdit is, as before, a stand-alone window -oriented application, 
rather than aline-oriented MPW tool. As with other conventional 
Mac applications, it can be called from within the MPW shell, 
although not as flexibly as an MPW tool. 

How to Get MPW 


MPW can be purchased by anyone from the Apple 
Programmer's and Developer's Association (APDA, 206-251- 
6548). If you haven't heard about APDA yet, you obviously 
haven't been reading the ads in MacTutor! АРРА is Apple's 
latest attempt to provide a mechanism for supplying technical 
information and software to the thousands of Mac owners out 
there who want it (though it also applies to the Apple IT). I can 
only hope it turns into a reliable and timely conduit for such 
information. 

If you're an APDA member ($20), you can order the base 
MPW configuration for $100; this includes the shell, utilities, 
assembler, linkers and, of course, the resource tools. The C and 
Pascal compilers are $75 extra; MacAppis $50, but it requires the 
Pascal compiler. 

However, the fine print in the APDA catalog says: 

This is a beta version of a product that will eventually be 
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sold through Apple retail outlets. Purchasing this version does 
not entitle you to a discount or free upgrade on the final product. 

This is, of course, the most anti-user upgrade policy pos- 
sible. Ontheother hand, this will probably have its desired effect, 
which is to discourage all but the most eager MPW-lover from 
buying it prior to its commercial release (The APDA/Dealer 
official status should be determined by Expo time, so check for 
an updatted status. It may be distributed to Apple dealers by this 
time.) 

Even if you decide not to get MPW, let's hope that third 
party companies license a version of the MPW resource tools, as 
the improvements over earlier tools are as dramatic as night and 
day. However, these improvements come at a price... 


La Plus Ca Change... 


Perhaps the one thing I retained from a semester of college 
French was the saying 


«La plus ca change, la plus la méme chose.» 


which is a fancy way of saying, "The more things change, 
the more they stay the same." 

The resource tools of the Macintosh Programmer's Work- 
shopare nothing like those of earlier development systems. They 
are radically different, definitely better, but are also completely 
incompatible. Macintosh developers have been suffering 
through a series of incompatibilities (when did YOU finally get 
an HFS-compatible update on your development system?), and 
this is the latest from Apple. (There is a clean migration path, as 
we'll see later.) 

On the other hand, I'd like to hand it to Apple for not being 
hide-bound to tradition and stifling innovation for the name of 
compatability. The new resource formats are also more clearly 
thought out, extensible, coherent and without the ad hoc flavor 
of their predecessors. (Besides, it gives writers like me a way to 
make money!) 

The MPW shell provides a demonstrable improvement in 
convenience and speed over most other development systems, 
which tend to use "Transfer" menus or their own mini-finder. 
The Think Technologies (Lightspeed C and Pascal) program- 
ming environmentis the only one Г ve seen of comparable power. 
Ironically, it is more Mac-like than Apple's MPW environment, 
which resembles a line-oriented operating system (e.g., UNIX) 
grafted onto a windowing computer (e.g., a Sun). The two 
approaches each have advantages, but I'd say the choice is more 
a matter of personal preference. 

However, there's no denying that when it comes to re- 
sources, MPW extends the standard for development systems. 
The two (and a half) new tools provide needed functionality, but 
more importantly, the MPW resource tools are far more flexible 
than their predecessors. 


The MDS Era 
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MDS and LI 
Alerts 


Application bundle 
Control 

Dialog/alert item list 
Dialog box 

File references 
General type 

Menu 

String 

List of strings 
Window 


Supported by Lisa only 
Arbitrary bytes from a file 


Control definition procedure 


16-by-16 cursor 

Driver/DA 

Text font 

Function key 

Font width table 

Hexadecimal literal 

32-by-32 icon 

List of icons (usually for Finder) 

Menu definition procedure 

Package 

8-by-8 pattern 

Pattern palette 

QuickDraw picture 

Window definition procedure 
*Implemented using PROC resources with MDS 
Table 1: Resource types for Lisa and MDS resource 
compilers 


By now, you're probably familiar with the Lisa resource 
compiler input format. It was the one used in the looseleaf 
Inside Macintosh and most of the early writing about Macin- 
tosh development. (Although I'd say there was disappoint- 
ingly little written about resources, which is one reason I 
volunteered to write Resource Roundup.) 

If you've ever used REdit to disassemble a resource, 
what you got was Lisa format. The Dialog Creator is another 
tool that uses this format. This is a nicely done and useful 
tool, but it would be a lot more useful if only it could read a 
resource fork of an application under development! 

So if you check your bookshelf, you've probably got all 
this documentation that uses the Lisa resource compiler. But 
if you're like me, a small-sized developer (or serious hobby- 
ist), you never could afford two machines, or at least justify 
the Lisa to the family finance committee. So instead, you 
purchased one of the many third party Mac-based develop- 
ment systems. 

Most of these systems borrowed some or all of their 
utilities from MDS, Apple's Macintosh 68000 Development 
System. So far, I've owned Microsoft Basic, UCSD Pascal 
(MacAdvantage), Megamax C, Rascal, TML Pascal, Mac- 
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METH Modula-2 and Lightspeed C. MS-Basic, MacMETH 
and Rascal don't include resource tools. All the others came 
with RMaker, the MDS resource compiler. 

RMaker and the Lisa resource compiler of course run on 
different machines. But from a documentation standpoint, the 
main difference is the input syntax. Dave Wilson published a 
list of the syntax of these two resource formats in a previous 
issue of MacTutor (Volume 2 No. 6 June '86). 

Table 1 shows the list of resource types supported by the 
two resource compilers. RMaker is more or less a subset of 
its Lisa counterpart. Those resources not supported by 
RMaker (or either one) must be input as GNRL resources. А 
the format of a GNRL-defined resource is not known by the 
resource compiler; instead, it is input with each instance of the 
resource. (This is an important difference from MPW, as 
we'll see later.) 

The definition of a GNRL resource begins with the target 
resource type, followed by a series of data fields. Each field is 
preceeded by .P,.I,.L,or.H, which allow specifying 
Pascal strings, integers, long intergers, or hex data by respec- 
tively. (Two other forms, .S and .R, are documented but 
rarely used.) Example 1 shows how the GNRL format is used 
to input a missing resource type under MDS. 

In the case of DLOG and BNDL resources, the formats are 
actually incompatible. Example 2 shows the MDS and Lisa 
equivalents of these resource types. 


What's New, Pussycat? 


The format of input to MPW's Rez is completely 
different. Unlike previous schemes, the syntax is consistent 
and not context-sensitive. 

For example, do you know what the remark delimiter is 
in the MDS/Lisa RMaker? If you answered “*”, you're half 
right. If you answered “;;”, you also get partial credit, since 
both are used in RMaker, depending on the position within 
the line. RMaker also may or may not ignore leading spaces, 
blank lines, and continuation characters, depending on the 
context. Get the idea? 

Under Rez and MPW, the remark syntax is the same no 
matter where it is used. As with a programming language, 
blanks and line breaks are ignored, except when part of an 
explicitly-delimited literal string. 

Glance at Example 3, which shows some sample Rez 
input data. The shock should be far less if you are an experi- 
enced C programmer: the format is similar to the constant 
initializers for a C struct. The use of delimiters for the 
Structure, strings and event comments are the same as C. Each 
of the fields of a resource (st ruct) are separated by com- 
mas. 

This is a logical development, since resources were 
always designed as a structured file format analogous to 
database records. The choice of C was a natural one, since C 
is (notoriously) terse, and also since Apple itself is discovering 
the value of C for systems programming. 
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TYPE ICON = GNRL 
, 128 

H 

0001 0000 0002 8000 0004 4000 0008 2000 
0010 1000 0022 0800 0044 8400 0089 0200 
0100 4100 0224 9080 0448 2040 0802 4020 
1124 8010 2249 0008 4480 3Ғ04 8124 4082 
4248 8041 2091 3022 1121 С814 084Е ТЕВЕ 
0412 3007 0221 0007 0100 8007 0080 6007 
0040 1ҒЕТ 0020 021Ғ 0010 0407 0008 0800 
0040 1000 0002 2000 0001 4000 0000 8000 


Example 1: Creating resources using GNRL 


Overall, Rez input is easier to read, mostly because of an 
increased availability of symbolic names. For example, is 

Cancel, visible, silent, 

Cancel, visible, silent, 

OK, visible, 2, 

OK, invisible, 1 


or 
СС61 


ап easier way to read ап ALRT stages word? On the 
other hand, it may be harder to write at first — more like a 
programming language, in fact — since there are balanced 
delimiters and misspelled keywords to worry about. 

Through the use of quotation marks to delimit strings, the 
new syntax eliminates the problems with spurious leading and 
trailing spaces in strings. Also, it's easy to continue long 
strings across record boundaries, because two successive 
strings (without a comma between them) are treated as one 
string. As with the earlier resource formats, Rez uses a C- 
style escape convention for special characters within literal 
strings. For example, the notation 'N0xOD", "vr" and "015" 
can be used for a Return character. 

Rez is run from within the MPW shell using a line- 
oriented command (no double-clicking here!), as in: 

Rez -o MyApp Types.r MyApp.r 

which takes a source text file called MyApp. r and writes 
the equivalent resource fork to MyApp, presumably your 
application. (Types . r will be explained in a minute.) If no 
output file is specified using -о, the output ends up in 
Rez.out, which isn't inspired, but reflects a consistent 
convention used by MPW tools. 

Rez (at least in 1.0b2) will clobber anything currently in 
the output file (including CODE resources). Fortunately, the 
MPW linker won't clobber anything other than CODE re- 
Sources, so as long as you Link more often than Rez, and 
always Link after Rez, you're in good shape. 

This is pretty easy to do, since MPW offers a UNIX-like 
Make facility, which attempts to guess at the minimum set of 
commands necessary for rebuilding. (MPW's Make, like the 
UNIX version, will err on the conservative side — extra 
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compiles — unless you override it.) Since the MPW shell 
includes a command programming language, you can also 
make a "brute force" command procedure to rebuild every- 
thing. 

But wait, there's more... 


How Do They Do It? 


The Rez resource compiler is completely extensible to 
cover any resource. The entire vocabulary is defined through 
a definition file, which you can change if you don't like the 
spellings or defaults. (A future installment of Resource 
Roundup will describe how to extend ResEdit.) 

This file, normally called Types . r, is a line-oriented 
text file with a syntax that (suprise!) resembles C. Rez is 
mostly just a program that understands how to read this file, 
and write resource data and maps. (The names of the resource 
attributes — such as sysheap, purgeable, locked — 
are hard-coded, but this is a minor inflexibility.) 

The definition syntax differs from C in that the names of 
the variables (fields) are missing, so the declaration consists 
only of the type of the variable, 


type 'ALRT 
{ 

rect; 
integer; 
integer; 


) 


/* bounds */ 
/* DITL id */ 
/* stages (cheating) */ 


so if you want the variable name, you have to include it 
as a comment. (The syntax provides a half-hearted support for 
arrays of variables and st ruct’s, and these do have a name.) 

Rez uses a slightly bastardized scheme of implementing 
enumerated variables. The enumerated names are listed right 
after the field name, without the braces used in C. As in C and 
Pascal, the enumerators are assigned to cardinal numbers, 


MDS format 


Type DLOG 
, 305 (32) 
60 90 190 422 
Visible GoAway ;; status 
305 2; corresponding DITL 
1 ;; Shape procedure 
0 j; reference value 
Align ;; Name 
Type BNDL 
, 128 
МАСА 0 2; Owner type and ID 
ICON! 3, desktop icons 
0 128 1 129 2 130 j; appl., 2 docs 
FREF j; file types 
0 128 1 129 2 130 j; (seme es ICN®) 
Lisa format 
Type DLOG 
, 305 (32) 
674 


60 98 190 422 3, boundary RECT 
Visible 1 GoAway 0 j; ргос10 and ref con 
305 j; corresponding DITL 
Align 
Type BNDL 

, 128 
МАСА 0 j; Owner type and ID 
2 ;; Number of types 
ICNS 3; desktop icons 
0 128 1 129 2 130 ;, appl., 2 docs 
FREF 3; file types 


0 128 1 129 2 130 j; (same as ICN®) 


Example 2: Different resource formats for MDS and 
Lisa resource compilers 


beginning with 0. Like C, the enumeration can be skipped to 
an arbitrary value by specifying it as a constant. Example 4 
shows how this is used in declaring different window 
(defprocs)in a WIND resource. 

Unlike C, a variant record is implemented using a quasi- 
executable syntax (the C switch), rather than as a union. 
The data value used to select the variant is a constant of 
arbitrary size and location within the variant record. 

If you're a Pascal, Modula-2 or Ada programmer, C's 
struct is similar to a Pascal record, but there are some 
other syntactic adaptations necessary: 


Description С Pascal 

Block () BEGIN END 
Remarks /* */ () or (* *) 
Hex constant OxAB SAB 

Alternate choice switch (е) CASE e OF 


Quotation marks ("double quotes") are used consistently 
for strings throughout. 

Example 5 shows the syntax of the input format for the most 
common resources. 


Finally, Written Output 


Did you ever want to print a resource? Things were fine if 
you always defined your resources in terms of RMaker input 
files; you could just print these out. But RMaker quickly got 
tedious for dialog box item lists, and icons, among other things. 

REdit was nice enough to decompile resources from the 
resource fork, but since REdit was designed to be a localization 
resource editor, not a developer's resource editor it, only under- 
stands a small subset of the commonly used resource types (see 
Resource Roundup, May 1986). For many of the resources that 
you most wanted to see, the output was just "No Format Speci- 
fication Available." 

Now that MPW has come along, what do you do if you have 
floppies full of RMaker source files that are useless? Or, 
suppose you abandoned RMaker for ResEdit — perhaps to 
support new resource types — and now you want to convert to 
using MPW. 
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As we say here in California, NOOOO PROBLEM!!!! 
When you're talking resources, DeRez is the second best re- 
source utility I've ever seen. (ResEdit is still my all-around 
favorite.) It allows you to decompile any resource to a text file, 
and if you don’t like the output, you can modify the definition file 
to get it into the form you want. 

Unlike executable code, compiled resources (a.k.a. the 
resource fork) contain nearly all the information that's in the 
source file, and can be decompiled to recover that info. 
(MacNosy is very ingenious, but a disassembler cannot recover 
the original Pascal source, including variable names). About all 
you lose in decompiling resources is the indentation and com- 
ments. 

In fact, Example 5 was originally written by DeRez, from 
aresource fork written by RMaker and modified by ResEdit! 
The comments and indentation were modified for compactness. 

DeRez is real easy to use and, not suprisingly, the true 
inverse of Rez. The command 


DeRez MDSsamp Types.r > MPWsamp.r 


decompiles the resource fork of MDSsamp, using the defi- 
nitions in Types . r, and writes the text output toMPWsamp. г. 
DeRez allows you to selectively include or ignore specific 
resource types or ID’s; for examples, you normally would want 
to 


DeRez -skip CODE 


Both options are a great improvement of REdit's decom- 
pilation, since I normally found myself wanting to look at a 
specific resource type from several different files, such as the 
menus (to design my own "File" and "Edit" menus, forexample.) 
That's a piece of cake; just type: 


DeRez -only MENU MacWrite Types.r 


to have the menus inserted into the current document. 

Of course, DeRez, like REdit, fails to provide a graphical 
record of those resources for which it would be appropriate, such 
as DITL's or PICT's. It would sure be nice if there were a tool 
to do that (is anyone listening out there?). For the time being, I 
take screen shots of the completed resources while in the appli- 
cation or one of the resource editors. 


The Sleuth 


When you need information on private parties, you call a 
private detective. If you want information on resources, then, 
naturally, it's time to call on the Resource Detective, RezDet. 

RezDet analyzes and validates resources far more rigor- 
ously than any other program, because that's its sole function, to 
validate resources. This means it's possible to manipulate a 
resource with DeRez or ResEdit, or for your program to use 
either the 64k ROM or 128k ROM resource manager. However, 
if RezDet takes a look, it may object to something the others 
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resource 'DLOG' (305, purgeable) ( 
(60, 90, 190, 422), /% boundary */ 
dBoxProc, /* procID */ 
Visible, /* visibility */ 
GoAway, 
0, /* refCon */ 
305, 
"Align"); /* Title */ 
resource 'BNDL' (128) ( 
МАСА”, 
0, 
( 'ICN8', /* desktop icons */ 
( 0, 128; /* application 
1, 129; /* document #1 
2, 130 /* document #2 


); 

'FREF', /* file types */ 

( 0, 128; /* application 
1, 129; /* document #1 
2, 130 /* document #2 


); 


resource 'ALRT' (128) ( 
(40, 40, 180, 240), 
128 
OK, visible, silent, 
OK, visible, silent, 
OK, visible, silent, 
OK, visible, silent 


/* Stage #4 */ 
/* Stage #3 */ 
/* Stage #2 */ 
/* Stage #1 */ 


resource 'DITL' (128) ( 
(/* Item #1 */ 
(104, 75, 124, 135), 
Button ( 
enabled, 
"OK" 


); 
/* Item #2 */ 
(12, 19, 93, 184), 
StaticText ( 
disabled, 
"eg" 
) 
) 


); 
Example 3: Sample Rez input 


have overlooked. 

Itenforces a canonical (standard) form on the resource map, 
header and data. Of course, it checks for invalid resource types, 
ID's, names and attributes. It looks for extra or missing data, 
inconsistent sizes (between the map and the resource), duplicate 
resource ID's or names. 

It has several output modes. At one extreme, the "quiet" 
mode returns a success/failure status to the MPW shell. At the 
other extreme, the error messages are printed above a dump of 
the resource data. Other options allow inclusions of informa- 
tion on each resource; no options prints only error messages. 

Example 6 shows the output of RezDet for the source 
shown in Example 5. The -show option is the least amount 
of information available (beyond the default print-out.) 


Summary 
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There are certain aspects of MPW that many will find 
unattractive. RAM and disk space requirements would be my 
main complaints. This package cost me at least $1,000 in 
hardware, which makes it the second most expensive piece of 
software I've ever owned, next to my original copies 
MacWrite and MacPaint (which included a Macintosh 128 at 
no charge!) 

[Note: plan on getting at least a 30 MB hard disk and 
preferably a 40 MB to support MPW. A twenty will fill up 
much too fast. -Ed] 

However, there's no doubt that the new tools for resource 
manipulation provided with MPW are more powerful and 
flexible than those they replace. For anyone who regularly 
uses resources, this is good news indeed. 


Follow-up to "Be a Keyboard Sleuth!” 


As many of you know by now, Volume IV of Inside 
Macintosh has been released, providing information on the 
changes between the original Inside Macintosh and features 
of the Macintosh Plus and the 128k ROM. 

Those of you who read “Ве A Keyboard Sleuth!" 
(Resource Roundup, August 1986) will understand why Apple 
added this passage to its revised "Macintosh User Interface 
Guidelines": 

To use arrow keys to make a selection, the user holds 
down Shift while pressing an arrow key. Application pro- 
grams that depend (as TextEdit does) on the numeric keypad 
Should not use these Shift-Arrow [sic] key combinations 
because the ASCII codes for the four Shift-arrow key combi- 
nations are the same as those for the keypad's +, *, 1, and = 
keys. If the use of Shift-arrow for making selections is more 
important to your application than the numeric keypad, the 
following paragraphs describe how it should work... 

For those of you who have forgotten about keyboard 
sleuthing, let me translate this for you: 

1) There is a new standard for extending a selection using 
cursor keys; 

2) There has been a standard mapping for entering 
symbols using the keypad; 

3) Because the Macintosh Plus is compatible with the 
Lisa and optional Macintosh keypad, four keypad symbols 
share the same keycode as the shifted cursor keys, to the 
extent that the shifted cursor keys return the same ASCII 
codes as their keypad counterparts; 

4) Therefore, standards 1) and 2) are inherently incom- 
patible. 

To resolve this problem, perhaps there could be yet 
another low-memory global (or even a bit) to provide a way to 
disable the emulation, e.g. 


BrDmgKPad DC.B 1; Ø is Lisa-like keypad 


Then applications that want to be able to tell the two 
apart can set the variable to non-zero, and reset it to zero prior 
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type 'WIND' 
( rect; /* bounds */ 
integer documentProc, dBoxProc, 
plainDBox, al tDBoxProc, 
noGrowDocProc ,rDocProc= 16; 
byte invisible,visible; 
fill byte; /* unused */ 
byte noClose, hasC lose; 
fill byte; /* unused */ 
longint; /* refcon */ 
pstr ing; /* title */ 


Example 4: Variant records in Rez definition 


to calling any desk accessories. Smart DA's would save this 
value and restore it upon exit, setting it to 1 in the meantime. 

Presumably a non brain-damaged keypad would return 
separate keycodes for cursor keys. At the very least, setting 
the flag would cause the Key2Trans routine to return a 
shifted arrow key with the same ASCII value as the unshifted 
key — $1C (left), $1D (right), $1E (up), $1F(down) — 
instead of $43, $42, $47 and $61 (“+*/=”.) The value of 
EventRecord.modifiers would, of course, include 
shiftKey. 

By publishing this user interface standard as it sits, Apple 
is encouraging developers to implement keyboard selection 
using the ASCII value of the shifted arrow key from the 
original Lisa keypad, long after the Lisa is dead and buried. 
I'm not privvy to Apple's sales figures, but my guess is that 
the number of Pluses sold at the end of 1986 will be 10 times 
the combined total of Lisas and optional keypads. Talk about 
the tail wagging the dog! 

The tea leaf readers say that Apple will offer a Macintosh 
68020-based engineering workstation and at least IBM PC 


resource 'ALRT' (129) ( 
(50, 50, 250, 250), 
129, /* corresponding DITL */ 
OK, visible, 3, 
Cancel, visible, 3, 
Cancel, visible, 3, 
Cancel, visible, 3 


); 


resource 'BNDL' (128) ( 
'WPNT', Ø, 
( 'ICN®', (9, 128; 1, 129); 
| 'FREF', (0, 128; 1, 129) 


J; 
resource 'CNTL' (128) ( 


(63, 141, 186, 172), 
/* initial value */ 


М 

invisible, 

1, 0, /* minimum, maximum value */ 
pushButProc, /* type of control */ 
0, /* reference constent */ 
"Stop" /* title */ 


) 


resource 'DITL' (128) ( 
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); 


resource 


); 


resource 


); 


resource 


); 


resource 


( (112, 112, 132, 192), /* Item #1 */ 
Button ( 
enebled, "OK" 


); 

(16, 64, 36, 235), /* Item #2 */ 
StaticText ( 

disabled, "Please enter your name:" 


(48, 8, 64, 56), /% Item #3 */ 
RadioButton ( 
enabled, "Mr." 


); 
(64, 8, 80, 56), /% Item 84 */ 
RedioButton ( 

enabled, "Ms." 


); 
(80, 8, 96, 56), /* Item 85 */ 
CheckBox ( 

enebled, "Dr." 


); 

(56, 72, 76, 250), /* Item "6 */ 
EditText ( 

enabled, "***Your name here***" 


'DLOG' (128) ( 


(100, 100, 254, 380), 


documentProc, /* window shape */ 
visible, 

noGoAway, 

0, /* refCon */ 

128, /* corresponding DITL */ 
"Dialog box" /* Title */ 


'FREF' (128) ( 
' APP 


L', /* file type */ 
0, /* corresponding ICN® */ 
ia /* name (not used) */ 


ad (128, preload) ( 


/* Data */ 

$'0001 0000 0002 8000 0004 4000 0008 2000" 
$'0010 1000 0020 0800 0040 0400 0080 0200" 
%"0100 0100 0200 0080 0400 0040 0800 0020" 
$" 1000 0010 2000 0008 4000 3Ғ04 82A8 4082" 
$'4288 8041 23A9 3022 12A1 C814 QAAE ТЕВЕ" 
$'0402 3007 0201 0007 0100 8007 0080 6001" 
%"0040 ІҒЕТ 0020 021Ғ 0010 0407 0008 0800" 
%"0004 1000 0002 2000 0001 4000 0000 8000": 
/* Mask */ 

%"0001 0000 0003 8000 0007 С000 000Ғ Е000" 
%"001ІҒ Ғ000 003Ғ Ғ800 OTF ҒС00 OOFF ҒЕ00" 
$"O1FF ҒҒ00 OSFF ҒҒ80 O7FF ЕЕС OFFF FFEO" 
$" FFF FFFØ 3FFF FFF8 ТЕРЕ FFFC FFFF FFFE" 
$"7FFF FFFF 3FFF FFFE 1FFF FFFC QFFF FFFF" 
$"O7FF FFFF @ЗЕЕ FFFF @1ЕЕ FFFF ØØFF FFFF" 
$"007F FFFF 003F FEIF 00ІҒ FCOT 000Ғ Ғ800" 
no Ғ000 0003 Е000 0001 С000 0000 8000" 


'WENU' (3) ( 

3, /* Menu ID */ 
textMenuProc, /* def proc */ 
OxTFFFFFFD, 

enabled, 


"Edit", — /* Menu title */ 
( "Undo", noIcon, "2", noMark, plain; 


, NOIcon, noKey, noMark, plain; 
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"Cut", noIcon, "X", noMark, plain; 
"Copy", noIcon, "C", noMark, plain; 
"Paste", noIcon, "V", noMark, plain; 


"Clear", noIcon, noKey, noMark, plain 


); 


resource 'STR ' (128) ( 
"This is my string" 


}; 
resource 'STR8' (128) ( 
( "One"; 
Two"; 
"Three" 
"Four" 
) 
); 


resource 'WIND' С 128) ( 
(40, 80, 240, 400), 
documentProc, 
visible, 
goAway, 


| "Untitled"/* Title */ 


Exemple 5: Rez input syntax for common resources 


RezDet -show MPWsamp 


"MPWsamp" : 

Type 0х4 14С5254 ‘ALRT': 
There is one item of this type. 
Reference list offset is 90. 
ID #129: 


There is no resource name. 


Attributes (0х0): 
Data offset is 0. 


Type 0x424E444C 'BNDL ': 
There is one item of this type. 
Reference list offset is 102. 
ID #128: 


There is no resource name. 


Attributes (0х0): 
Data offset is 16. 


Туре 0х434Е544С ‘CNTL': 
There is one item of this type. 
Reference list offset is 114. 
ID #128: 


There is no resource name. 


Attributes (0х0): 
Deta offset is 56. 


Туре 0х4449544С 'DITL': 
There is one item of this type. 
Reference list offset is 126. 
ID #128: 


There is no resource name. 


Attributes (0x0): 
Data offset is 87. 


Type 0х444С4Ғ47 'DLOG': 
There is one item of this type. 
Reference list offset is 138. 
ID 8128: 


There iS no resource name. 


Attributes (0x90): 
Data offset is 235. 


/* window shape */ 


/* reference constant */ 
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Type 0х46524546 'FREF': 
There is one item of this type. 
Reference list offset is 150. 
ID ** 128: 


There is no resource neme. 


Attributes (0х0): 
Data offset is 270. 


Type 0х49434Е23 'ICNS': 
There is one item of this type. 
Reference list offset is 162. 
ID #128: 


There is no resource name. 


Attributes (0x4): Preload 
Data offset is 281. 


Type 0х40454Е55 'MENU': 
There is one item of this type. 
Reference list offset is 174. 
ID #3: 


There is no resource name. 


Attributes (0х0): 
Data offset is 541. 


Type 0х53545220 'STR ': 
There is one item of this type. 
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Reference list offset is 186. 
ID #128: 
There is no resource name. 
Attributes (0x9): 
Data offset is 61T. 


Type 0х53545223 'STRS': 
There is one item of this type. 
Reference list offset is 198. 
ID #128: 
There is no resource name. 
Attributes (0х0): 
Data offset is 639. 


Туре 0x57494E44 ‘WIND’: 
There is one item of this type. 
Reference list offset is 210. 
ID #128: 
There is no resource name. 
Attributes (0x0): 
Data offset is 664. 


The resource fork of MPWsamp appears to be OK. 


Example 6: RezDet output for Example 5 
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MacCad 


Workstation Potential of the New Macs 


Paul Zarchan is an engineer for a well known east 
coast laboratory with a heavy investment in engineer- 
ing workstations. In this article, Paul examines the 
potential of the new Macs to penetrate the world of 
Sun, Apollo and other desktop CAD systems. MacTu- 
tor is committed to covering this important applica- 
tions development area of MacCad on the new Macs 
in the coming year and this is our first article for this 
new column. 


Introduction 

Today there are nearly 10 million personal computers in 
both the home and business world, including nearly 1 million 
Macs, according to Apple's press releases. Much has improved 
with personal computer hardware since the first Apple II was 
introduced 10 years ago. In addition, the personal computer 
industry has spawned the creation of new software applications 
such as word processing, spread sheets and desktop publishing. 
These desktop computers also have another, albeit relatively 
unknown capability - computing! It will be demonstrated that a 
currently available $6,000 Prodigy 4 (Macintosh plus Levco 
board) can run engineering simulations at approximately one half 
the speed of a $250,000 super mini-computer and about one tenth 
the speed of a multi million dollar mainframe. With the advent of 
a new family of Macintosh Workstations based on technology 
similar to the Prodigy board, it is expected that Apple will move 
heavily into the engineering workstation market. How effective 
will this new market be for Apple? If this article is any indication, 
the new Macs will be quite successful indeed! 


A New World for Micros 

Digital computer simulation is often used as an aid in 
solving many engineering problems. For example, simulation is 
the heart of many circuit analysis programs. In this application, 
system dynamics are modeled with differential equations and 
numerical integration techniques are utilized for solving these 
equations. Unlike most PC software applications, the speed of 
floating point arithmetic is critical to simulation. A slow com- 
puter or inefficient language can make the simulation of high 
order systems unattractive because of excessive computation 
time. It will be demonstrated that for simulation on a Macintosh, 
MacFORTRAN provides execution speed that is unmatched by 
any other high level language. A chart is presented showing how 
to predict execution time based upon system order, simulation 
time and integration step size for simulations written in FOR- 
TRAN on a variety of computers. 


A simple, standard floating point benchmark, written in 
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interpretive BASIC, is first used to compare a variety of 8, 16 and 
32 bit commercially available PC's. Based upon the relative 
computer execution speeds, an empirical relationship involving 
number of bits and computer clock rate is developed not only to 
understand why certain micros are faster than others but also to 
be able to predict the relative speeds of PC's which are not yet 
commercially available. Next a simulation example, involving 
the transient response of a Butterworth filter, is programmed in 
FORTRAN. It is demonstrated that although this more realistic 
example yields different speed comparisons between micros as 
did the BASIC floating point benchmark, the trend is in the same 
direction - more bits and higher clock rates increase computation 
speed. The same simulation example is then run on a Macintosh 
computer using a variety of computer languages. Itisshown that 
on this computer FORTRAN and compiled BASIC offer compu- 
tation speeds superior to that of either compiled PASCAL or C. 
Finally, using FORTRAN as the common language for the 
simulation example, a variety of micro, super mini and main- 
frame computers are compared in terms of execution speed. It is 
shown that a 32 bit 16 Mhz Prodigy 4 (Macintosh computer plus 
Levco board) can run simulations at approximately one half the 
speed of a VAX 785 and approximately one tenth the speed of an 
IBM 3084Q. 


Microcomputer Comparison 

In order to compare micro-computer speed, a common 
example written in a common language is required. А standard 
benchmark, representitive of single precision arithmetic, was 
developed by BYTE magazine using the BASIC language. The 
BASIC language was chosen as the standard because it is 
available on all micro-computers. The program listing appears 
below. Note that the question of accuracy, which of course is vital 
to engineering applications, is not address here. 


10 PRINT TIME$ 
20 az2.71828 

30 b=3.14159 

40 с=1 

50 FOR i=1 TO 5000 
60 с=с*а 

70 c=c"b 

80 с=с/а 

90 czc/b 

100 NEXT i 

110 PRINT TIME$ 
120 END 


Listing 1- BYTE Floating Point Benchmark 
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Clock 
Rate (Mhz) 


Machine 


Commodore 128 
Apple 2E -6502 
IBM PC, XT - 8088 
Tandy 1000 - 8088 


IBM AT - 80286 
Compaq 286 - 80286 
Atari 520 ST - 68000 
Amiga - 68000 
Macintosh 512, Plus * 


Compaq 386 - 80386 
Prodigy 4 - 68020 
* Language was MS Basic 3.0 Interpreter 


We can see from the listing that the program executes 
10,000 single precision multiplies and divides. The timing 
results for a variety of commercially available PCs along with 
other information, appears in Table 1. In addition, the last 
column of Table 1 indicates resultant running times compared to 
an IBM PC in the form of a ratio. A ratio of 2.2 means that the 
indicated microcomputer was 2.2 times faster than an IBM PC for 
this BASIC benchmark. We shall see later that the ratios for 
computer speed using BASIC on this benchmark are indicative 
of relative computer speeds using other languages and more 
realistic problems. 


20 


PREDICTED , 


mean 


- 
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IBM 
MACINTOS 
AMIG 
COMPAQ 386 
PRODIGY 4 


Fig. 1 Speed Improvement Predicted 


Table 1 indicates that the microcomputers fall into three 
different speed classes. Generally these speed classes are a 
function of the number of bits and computer clock rates. The 
table shows that, contrary to popular opinion, the 16 bit 80286 
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based IBM AT is in the same class as the 68000 
based 16 bit Atari, Macintosh and Amiga com- 
puters for the BASIC benchmark. The Table 
also showsthat computer clock rate is important 
in determining computer speed. In fact, dou- 
bling either the clock rate or doubling the 
number of bits doubles the computer speed. For 
example, a Prodigy 4 is approximately 4 times 
as fast as a Macintosh (32 bits - 16 Mhz versus 
16 bits - 7.5 Mhz) anda 6 Mhz IBM AT is nearly 
2.7 times faster than an IBM PC (16bits - 6 Mhz 
versus 8 bits - 4.77 Mhz). In the IBM world the 
importance of clock rate is well known. That is 
why there exist many third party upgrades to in- 
crease the clock rate of an IBM AT or compat- 
able up to 12 Mhz. Figure 1 displays in bar chart 
form, the actual speed for the BASIC bench- 
mark of various micros relative to an IBM PC. 


Ratio 


1.15 


Superimposed on the chart is a line graph using the empirical 
relationship involving bits and clock rate. The proximity of the 
line graph and bars shows that the simple empirical relationship 
is quite accurate in the case of the standard BASIC benchmark. 


Simulation Example 


In order to compare various machines, a more realistic 
example, representitive of simulation, is taken from filtering 
theory. A sixth order Butterworth filter can be represented by the 
transfer function: 


y 
x 3 4 6 
а 6 dee a_s Pa a sf ac? 
1. ds p EL o. ss _ 
о 6 
Qo @ 0] (A) 
0 0 0 ^ Д ” 


where x is the filter input, y is the filter output, w, is the natural 
frequency of the filter and s is the Laplace transform notation for 
a derivative. The coefficients of a sixth order Butterworth filter 
are given by: 
a, = 3.86 
a, = 7.46 
a, = 9.13 
‚ = 7.46 
, = 3.86 
a, = 1 
Cross multiplying the numerator and denominator of the 
transfer function and solving for the highest derivative yields the 


a eae" ыға өзеге 
Vu б [шун mr ug» ME NY 
a m 2 3 4 5 
о) 
6 0 % % 0 = 
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Fig. 2 Block Diagram of Sixth Order Butterworth Filter 


following sixth order differential equation: 


where each "dot" represents a differentiation. This differential 
equation can be represented in block diagram form as shown in 
Fig. 2. In this diagram each "1/s" represents an integration. The 
output of each integrator has been labeled x(1) thru x(6). 

For simulation purposes itis more convenient to express the 
sixth order differential equation describing the Butterworth filter 


x(1) = x(2) 


x(2) = x(3) 

x(3) = x(4) 

x(4) = x(5) 

x(5) = x(6) 

x(6) = 9 и E a ERN 
a 6 % a o Ф a _ 


by 6 first order differential equations. These equations сап be 
obtained from Fig. 2 by inspection and are given by: 


А FORTRAN listing of the simulation of the sixth order 
Butterworth filter appears below. 


INTEGER ORDER 

DIMENSION X(6),XOLD(6),XD(6) 

DATA B1,B2,B3,B4,B5,B6,W0/3.86,7.46, 
9.13,7.46,3.86,1.,50./ 


10 


20 


30 


40 


999 


W05=W04*W0 

W06=W05*Wo 

DO 10 I=1,ORDER 

X(1)=0. 

CONTINUE 

T=0. 

H=.0001 

6-0. 

IF(T.GE..5)GOTO 999 

S=S+H 

DO 20 le1,ORDER 

XOLD(I)=X(I) 

CONTINUE 

CALL INTEG(T,XD,X,W02,W03,W04,W05,WO06) 
DO 30 I=1,ORDER 

X(1)=X(I)+H*XD(I) 

CONTINUE 

T=T+H 

CALL INTEG(T,XD,X,W02,W03,W04,W05,WO6) 
DO 40 l=1,ORDER 
X(1)=(XOLD(1)+X(I))/2.+.5*H*XD(1) 

CONTINUE 

IF(S.GE..004999) THEN 

6-0. 
WRITE(9,*)T,X(1) 
ELSE 

END IF 

GOTO 5 
CONTINUE 

END 
SUBROUTINE 
SAVE 

INTEGER ORDER 
DIMENSION X(6),XOLD(6),XD(6) 

DATA B1,B2,B3,B4,B5,B6,W0/3.86, 7.46,9.13, 


INTEG(T,XD,X, W02, W083, W04, W05,W06) 


DATA XIN/1./ 7.46,3.86,1.,50./ 
ORDER=6 DATA XIN/1./ 
W022WO*WO ORDER=6 
W03=W02*W0 XD(1)=X(2) 
W04=W03*W0 XD(2)=X(3) 
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XD(3)=X(4) 

XD(4)=X(5) 

XD(5)=X(6) 

XD(6)=W06*(XIN-B5*X(6)/W05-B4*X(5)/W04- 
B3* X(4/W03 -B2*X(3)/W02-B1*X(2)/WO0-X(1))/B6 

RETURN 

END 


FP Co- 


Listing 1 - FORTRAN Simulation of 
Sixth Order Butterworth Filter 


We can see from the listing that the integration step size, H, 
is .0001 sec and that the numerical integration method is second 
order Runge-Kutta. Sincethe simulation time is 0.5 sec, the ratio 
of the simulation time to the step size is 5000. This means that 
10,000 passes are made to the integration subroutine. The 
extremely small integration step size was chosen to ensure 
accurate answers if the natural frequency of the filter was made 


SIXTH ORDER BUTTERWORTH 
STEP RESPONSE 


о = 50 RAD/SEC 


0.0 0.1 0.2 0.3 0.4 0.5 
TIME (SEC) 


much larger. The resultant filter transient response due to a step 
input (x21), as obtained on any of the 8, 16 or 32 bit micros tested 
is shown in Fig. 3. 


FORTRAN Comparison 


So far it has been shown how the various microcomputers 
perform relative to one another in terms of single precision 
floating point multiplies and divides for the BYTE BASIC 
benchmark. The simulation of the sixth order Butterworth filter 
with the FORTRAN source code of Listing 2 is now solved on 
PCs representitive of the 8, 16 and 32 bit world and their running 
times are compared. 

The machines used in this comparison are the original IBM 
PC, an improved PC, an IBM AT, a Macintosh and Prodigy 4 
microcomputers. First we must determine if the relative speeds 
between computers for the BASIC benchmark is indicative of 
speed ratios for this more realistic simulation example written in 
the FORTRAN language. The performance of the machines are 
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processor 


Out- Not used 


In- Used 


Mac 
Plus 


Improved | IBM 
PC AT 


35 sec 


Table 2 - FORTRAN Running Time Comparison 


Prodigy 
4 


15.4 sec 


520 sec | 75sec 61 sec 


40 sec 7.4 sec 


compared with and without math co-processors. Table 2 


presents the running time comparisons. 


First we notice that the original IBM PC is very slow, 
relative to the other machines on the simulation example - much 
slower than was predicted by the BASIC benchmark. However 
newer versions of the 4.77 MHz, 8 bit IBM PC and clones are 
significantly faster and their speed relative to other machines is 
more accurately predicted by the BASIC benchmark. For ex- 
ample, the IBM AT is about twice as fast as the improved IBM 
PC and the Prodigy 4 is four times faster than the Macintosh as 
was predicted by the BASIC benchmark. Addressing the math 
со-ргосеѕѕог significantly improves the speed of both the Prod- 
igy 4 and improved IBM PC. However addressing the math co- 
processor on an IBM AT results in negligible speed improve- 
ment. The performance improvement for the IBM AT is not as 
significant because the math co-processor operates at 4 Mhz 
while the machine is running at 6 Mhz. Figure 4 depicts the 
relative speed comparisons between machines relative to the 
original IBM PC for the simulation example. Here we can see 
that the 32 bit Prodigy 4 is nearly 35 times faster than the original 
8 bit IBM PC. When the math co-processor is addressed it is 


NO MATH CO-PROCESSOR 
FORTRAN LANGUAGE 
30 BUTTERWORTH EXAMPLE 


20 


IBM PC 


SPEED 


10 


- 
S < 
= 
5 © 


MACINTOSH 
PRODIGY 4 


Fig. 4 Relative Speed Performance for 
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IBMPC IBMAT 


Prodigy 4 


VAX/785 


520 sec 35 sec 7.4 sec 3.1 sec 


nearly 70 times faster. Clearly much has improved since the 
introduction of the first IBM PC 5 years ago. 

The sample problem was also run in FORTRAN on two 
super mini-computers and one mainframe computer. The run- 
ning times are summarized in Table 3. 

In this table the running time for the larger machines 
corresponds to CPU time with a single-user load on a time- 
sharing system. Usually large machines are shared among many 
users and the CPU time is indicative only of what the user is 
charged for a session. In addition, on large machines the turn- 
around time (the elapsed time it takes the user to get the output) 
may be hours even though the CPU time may be in seconds. On 
a micro ће CPU time is the turn-around time. Nonetheless, Table 
3 indicates that the Prodigy 4 is only 2.4 times slower than the 
VAX/785 and 12 times slower than the mainframe. Considering 
that the Prodigy 4 costs about $6,000 whereas the VAX/785 is 
about $250,000 and the IBM/3084Q is several million dollars - 

the comparison is more impressive. More importantly, the 
sample problem could be solved on any of the machines in a very 
reasonable amount of time. In the case of the microcomputers - 


S = SIMULATION TIME 

N = SYSTEM ORDER 

Н = INTEGRATION INTERVAL 
S*N 


H 


COMPUTATION UNIT = 


IBM AT 


RUNNING TIME (SEC) 


PRODIGY 4 
IBM 3084Q 


VAX 785 
10? 10^ 10? 109 10 
COMPUTATION UNIT 

Fig. 4 Computer Running 

Time for Given Problem 
the user gets the answers immediately whereas on the larger 
machines the turn around time may be significantly longer. 

The answers for the sample FORTRAN problem were for 6 

differential equations, a simulation time of 0.5 sec and and 
integration interval of .0001 sec. Doubling the simulation time, 
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VAX/8600 


‚74 sec 


doubling the number of differential 
equations or halving the integration 
interval will work in the direction 
of doubling the computer running 
time - regardless of computer. 
Figure 4 presents computational in- 
formation so that an engineer can 


TEM ma the computer running 
time for a given problem. All that has to be done is to multiply 


the number of differential equations by the simulation time and 
divide by the integration step size in order to compute the 
abscissa of the figure. The computer running time in seconds is 
the ordinate. 

For example the simulation of 100 differential equations in 
FORTRAN for a 10 sec simulation with an integration step size 
of .01 sec would require a run time of 1730 sec on the original 
IBM PC, 116 sec оп an ІВМ AT, 24.7 sec оп a Prodigy 4, 10.3 
sec on a VAX/785 and 2.03 sec on an IBM/3084Q. 


IBM/3084Q 


.61 sec 


Languages 


FORTRAN was the first high level language introduced on 
a large scale. It was first proposed in the 1953-1954 time frame 
by Jim Backus of IBM. The goal of this language was to 
demonstrate that a high order language could be developed 
which would produce programs as efficient as hand coded 
programs in machine language for a wide class of problems. The 
objective of FORTRAN at that time was to make programming 
on the IBM 704 computer much faster, cheaper and more 
reliable. Originally the FORTRAN language reflected the hard- 
ware constraints of the IBM 704. Due to the popularity of the 
language other computer manufacturers developed other ver- 
sions of FORTRAN, tailored to their own hardware. By 1963 
virtually all mainframe manufacturers committed themselves to 
some version of FORTRAN. Since that time FORTRAN has 
evolved eliminating undesireable features and adding some 
elements of structured programming. 

PASCAL was developed in the late 1960's by Niklaus 
Wirth of Eidgenossische Technische Hochschule in Zurich. The 
principal aims of PASCAL were: 

(1) - to make available a language suitable to teach program- 
ming as a systematic discipline based on certain funda- 
mental concepts clearly and naturally reflected by the 
language (structured programming) 


(2) - to develop implementations of this language which are 
both reliable and efficient on presently available comput- 
ers. 

The first PASCAL compiler was available in 1970. PAS- 
CAL has gained widespread acceptance as a teaching language 
for structured programming. 

BASIC was originally developed in 1963 at Dartmouth 
College by John Kemeny and Thomas Kurtz. The language was 
originally designed for beginners with interactive computing in 
mind. By 1970 the language had grown so that itcould handle the 
most sophisticated and complex applications. During the 1970's, 
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as graphics devices became available, easy-to-use graphics 
commands were added to the language. When microcomputers 
first appeared, BASIC was the most popular language for im- 
plementation on them, because it was a clean and simple lan- 
guage. 

Although, commonly implemented as an interpretive lan- 
guage, excellent compilers exist today for BASIC in both the 
IBM and Apple microcomputer world. Although generally 
scorned by professional programmers, BASIC continues to be 
the worlds most popular programming language because it is 
easy to use and is generally included, without cost, with each PC 
purchase, at least until the Macintosh came along! 

C is a general purpose programming language. It has been 
calleda "systems programming language" because itis useful for 
writing operating systems. It has been used in the microcomputer 
world to write major text processing and data-base programs. C 
is a relatively low level language when compared to either 
FORTRAN or PASCAL. This language stems from the language 
BCPL, developed by Martin Richards. The influence of BCPL 
on C proceeded indirectly through the language B which was 
written by Ken Thompson in 1970 for the first UNIX system on 
the PDP-7. 

For a given machine the choice of language makes a 
significant difference in the computer running time. Interpretive 
languages, such as BASIC, are slower than compiled languages 
such as FORTRAN. However interpretive languages, due to the 
friendly debugging environment, often reduce the program 
development time. If one has to develop a program quickly and 
only run it a few times an interpretive language like BASIC might 
be the best choice. If the program has many differential equations 
and will be run many times, a compiled language such as 
FORTRAN might be a better choice. 

Several popular microcomputer languages were used on the 


Language Type Use Running 
SANE Time (Sec) 

MBASIC 2.1 Interpretive No 784 

Mac Pascal Interpretive Yes 1804 

True Basic Intermediate No 242 

MS BASIC 1.0 Compiled No 159/78 * 

Z Basic Compiled No 412 

TML Pascal Compiled Yes 425 

Lightspeed Pascal Compiled Yes 505 

Light Speed C Compiled Yes 410 

Aztec C Compiled Yes 620 

MacFortran Compiled No 61 


* Faster time obtained with dynamic arrays 


Table 4 - FORTRAN is the Fastest Language 


sample problem of the previous section and the computer run- 
ning times on a Macintosh are summarized in Table 4. 


Surprisingly, although C is the de facto standard for com- 


684 


mercial program development on microcomputers, it is nearly as 
slow as interpretive BASIC for problems involving floating point 
computation on the Mac. Similarly, although PASCAL is the 
standard in many educational institutions, it is very slow for 
problems involving the integration of differential equations. The 
Slowness of C on the Macintosh for simulation type problems is 
due to floating point operations. Both C and PASCAL use the 
standard package provided by Apple for floating point opera- 
tions, called SANE. However BASIC and FORTRAN developed 
their own software floating point programs. In these packages 
there was a reduction in accuracy at greatly improved speed. The 
accuracy of both BASIC and FORTRAN in single precision for 
the sample problem was sufficient to get the correct answers. The 
table also shows that when BASIC is compiled, it is faster than 
either C or PASCAL. In the case of the Macintosh, FORTRAN 
is clearly the language of choice when speed is an issue. 

Of the Macintosh languages considered only FORTRAN 
for now can take advantage of the 68881 math coprocessor. 
Table 5 shows the running time for all the languages ona Prodigy 


Language Use Running- 
Co-processor Time (Sec) 

MS BASIC 2.1 No 201 

Mac Pascal No 406 

True Basic No 62 

MS BASIC 1.0 No 38/18" 

2 Вавіс Мо 96 

TML Pascal No 63 

Lightspeed Pascal No 83 

Lightspeed C No 75 

Aztec C No 115 

MacFortran No 15.4 

MacFortran/020 Yes 7.4 


* Faster time obtained using dynamic arrays 


Table 5 - Using Math Coprocessor Reduces 
Running Time on Prodigy 4 By Factor of 2 


4 (Macintosh plus Levco board). 


We can see that BASIC and FORTRAN reduced running 
times by a factor of 4 when the Prodigy 4 was used. The reduction 
of running time was due to doubling the bits and clock rate from 
the Macintosh computer. On the other hand, running times 
reduced more significantly for Pascal and C. The reason for this 
is that both Pascal and C use the Apple numerics library, SANE, 
for floating point computation. The Prodigy 4 intercepts calls to 
this library and re-routes them to the math coprocessor. It is 
hoped the new Macs will also have this ability. 

Conclusions 

The purpose of this paper was to demonstrate that problems 
involving the integration of differential equations can expect to 
be simulated to great advantage on the new Macintosh Worksta- 
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tions. Simulation speed can be enhanced by using a language 
built for floating point speed such as FORTRAN. The paper 
demonstrates that the 32 bit, 16 Mhz Macintosh with Levco 
board costing $6,000 can perform simulations in FORTRAN at 
approximately one half the speed of a $250,000 super mini- 
computer and approximately one tenth the speed of a multi 
million dollar mainframe. It is expected this same capability will 
be present in the next Macintosh generation, recently announced. 
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A Minimal 68020/881 Add-on 
by John R. Novy, Novy Systems Inc. 


Most Macintosh upgrades using the 68881 coprocessor 
include 32 bit memory enhancements and processor speed im- 
provements. Such an upgrade is the Levco Prodigy 4 which 
increases the CPU clock rate to 16 MHz and adds 32 bit wide 


memory. Cost effective improvements may be obtained from a 
minimal upgrade which does not include the features of either a 
32 bit memory or increased processor speed. Applications which 
are floating point intensive are improved as much by the use of 
the coprocessor as by added memory or increased processor 
speed. Thisis shown by the Fortran benchmark in Paul Zarchan's 
article which documents an improvement of about 200% when 
using a coprocessor in the IBM PC or Prodigy 4. 

Based on Paul's article we would expect a 68881 coproces- 
sor, with no increase in processor speed, to show a 200% 
improvement in the Macintosh run time of 61 seconds. Using a 
Novy Systems MAC2O (with the 020 cache disabled, and not 
using Fortran/020) aruntime of 31 seconds was obtained, which 
is an improvement of about 20096. The cache was disabled to 
approximate 68000 performance. The Novy Systems MAC2O is 
an implementation of a 68020 running at 7.8 MHz with a 68881 
and no additional memory. With the cache enabled the 68020/ 
881 combination ran in 22 seconds for an improvement of about 
300%. A run time of 17 seconds was obtained when Fortran/020 
was used to duplicate the testing done on the Prodigy 4. 

The advantage of a minimal system is, for many applca- 
tions, a throughput improvement of 200 to 400% ata much lower 
cost. The Novy Systems MAC20, at less than $750, can run 
simulations at approximately one half the speed of a maximum 
system upgrade for less than one sixth the price. 
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Expo Report 
Ву 
David E. Smith MacTutor Vol. 3 Мо.3 


Award Winner! 

MacTutor won two awards recently. Bruce Webster in his 
According to Webster Byte column named MacTutor as the 1986 
Fritzie winner for Best Publication Other than Byte (naturally), 
in the January '87 issue of Byte magazine. Bruce had lots of good 
things to say about us so please pick up a copy of Byte and read 
his nice remarks. On top of the Fritzie award, Redgate's Macin- 
tosh Buyer's Guide voted MacTutor one of the top 100 Macin- 
tosh products of 1986. The only other two magazines so chosen 
were MacWorld and Mac User. We were presented a nice award 
at a fancy party hosted by John Sculley and other Apple and 
industry big-wigs at the Expo. Our Mona Crompton stood right 
next to Bill Gates of Microsoft, but was too shy to introduce 
herself! The MacTutor girls (Mona, Shelley and Laura) were the 
hit of the party list, at least the parties that had dancing! 

Expo Review 

The MacWorld Expo held in San Francisco in January was 
a smashing success and really provided a forum for Apple's John 
Sculley to tell the world "I told you so" as the number of people 
and products broke new records for a single computer vendor 
show. The energy and industry excitement proved that 1987 will 
be the Year of the Mac. Apple people said more about the new 
Mac computers without actually mentioning them than I thought 
possible. This is truly the world's most announced unannounced 
computer of all time! Sculley also defended the 68000 family as 
the best decision Apple ever made and he made it clear that Apple 
and Motorola will continue to work closely together to bring the 
new -20, -30, and 78000 chips into future Mac hardware, which 
Apple apparently has planned out well into the 1990's. I believe 
this show proves we are entering the Golden Age of the Macin- 
tosh. Apple even made the cover of Business Week Magazine as 
the darling of Wallstreet again! Here is my view of the show. 

Pagemaker fell from grace as the number one page layout 
program as version 2.0 was delayed another month while Aldus 
Corp. brings out the PC version. The current Pagemaker 1.2 
remains buggy and crashes when trying to edit large numbers of 
disjointed text items. It seems that the internal design is based on 
resources and makes heavy use of the resource manager. This 
resulted in several versions of the system file as Aldus uncovered 
bugs in Apple's resource manager. But the resource design 
apparently still cannot cope with text editing properly and so 
Aldus has ripped out the resource base and re-designed the text 
editing in version 2.0 to eliminate the bugs. The new boy on the 
block is now Ready Set Go 3, from Manhattan Graphics, 
which has all the features Pagemaker is saving for version 2.0, 
including the placement of postscript files. Other features of 
Ready Set Go 3 not yet included in Pagemaker are hyphenation, 
kerning, and text placement around arbitrarily shapped graphics. 
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The manual for Ready Set Go 3 was written by David Kater, an 
old school buddy of mine. It is done in the form of a magazine and 
appears more than adequate. 

The politics of desktop publishing were evident at the show 
as Letraset proved it is a company with money to burn. It seems 
that Letraset bought the rights to Boston Publishing System's 
MacPublisher II and planned to introduce a version of it as their 
own LetraPage software. But when they saw Ready Set Go 3, 
they decided that product was better so they dumped MacPub- 
lisher and bought up the marketing rights to Ready Set Go 3! This 
left Boston Publishing withouta product, so they have taken back 
the marketing rights and had a small booth at the show 
advertising MacPublisher III, along with a plea for dealers to 
make themselves known so they could re-create their customer 
base. Which still leaves the question of what exactly is Letraset 
going to do for Ready Set Go 3? Word has it that they will bump 
up the price from $295 to $395. Will Manhattan Graphics regret 
the day they sold out? We think so. Stay tuned for more in the 
continuing saga of Under the Desktop! 

Having trouble with your power supply? One solution is to 
reduce the power drain of the Mac by increasing the memory 
from one meg to four megs. Does that sound like a contradiction? 
Dove Computer Corp. has introduced MacSnap Plus 4H simm 
modules that use low power 1 meg dynamic ram chips which 
actually lower the total power drain of the Mac because the chips 
use less power than the present 256K chips in the Mac. Truly a 
case of "get more for less"! The simm modules simply plug in and 
replace the present four Mac simm modules in a Mac Plus. This 
looks like a good way to both upgrade and reduce the margin for 
error on the touchy Mac analog board. We just paid for our 
second analog board swap in six months here at MacTutor so you 
can bet we will be calling: (919) 763-7918. 

MacMemory had a cute idea. They advertised the price 
difference between the Prodigy 68020 upgrade and their own 
TurboMax 68000 board, which doubles the clock speed from 8 
mHz to 16 mHz. They said you could buy Excel (the software) 
and Excel (thecar) for the price of a Prodigy and still have enough 
left for the TurboMax. They even had a car in their booth to 
illustrate it! Problem is, the price of the Prodigy was reduced at 
the show so the ad was no longer true. No problem. They ran over 
to Jim Fitzsimmon's Mac America booth, and printed out a fine 
print addition: slightly used Excel (the car). Another cute trick: 
they had two Macs running from a single mouse so they could 
show the speed difference with the same programs running on 
both. It was impressive, but I want a 68020 chip in mine. 

Microtek introduceda flat bed scanner that allows books to 
be scanned much like acopy machine. Model MSF-300 supports 
half tones and line art at 300 dpi with eight half tone screens 
producing up to 64 gray levels. The new scanner is a much nicer 
looking package than the older model MS 300, which looked like 
the Abatron unit. Also, new Mac software called VersaScan 
Plus is said to further position the Microtek unit out in front over 
the Abatron scanner in the battle for scanner supremacy. (213) 
321-2121. 

Layout Programs 
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Postscript is replacing Quickdraw as the fundamental 
graphics definition on the Macintosh and many new postscript 
based drawing programs were introduced at the show. The 
advantage of using Postscript is that it speeds up printing on the 
LaserWriter and allows access to the full power of the printer, 
which is much greater than that available through Quickdraw. 
Cricket Draw from Cricket Software was one of the first of 
these new postscript based draw programs. It allows you to create 
postscript files from a Mac drawing environment or edit post- 
script text. With the new Ready Set Go 3 and the not-yet- 
available Pagemaker 2.0, you can place the postscript output of 
Cricket Draw in your page layout software. (215) 387-7955. 

Another postscript tool is PostHaste from Micro Dynam- 
ics, Ltd. This inexpensive utility provides a postscript editor and 
LaserWriter downloader for Appletalk. (301) 589-6300. (See 
their ad in this issue.) 

LaserPaint from LaserWare is another drawing/editing 
program that creates postscript output. The drawing portion 
supports arcs and spirals, filling with screens, custom dashed 
lines and line widths from hairline to 99 pixel widths. The 
painting portion has AirBrushing and full resolution Bitmaps up 
to the limit of the LaserWriter. The text portion supports full 
leading, kerning, text on any defined path, and runaround text 
justifying inside or around any picture. Another neat feature is 
that this program allows full color separations for ad copy work! 
LaserWare also markets a Laser Font maker called Laser Works 
1.2, which is similar to Fontographer. Unfortunately, it is copy 
protected. (415) 453-9500. 

For the dedicated typesetter, MacTex from FTL Systems 
may be the most powerful postscript based typesetting software 
available for the Mac. The kerning, leading and hyphenation are 
said to be far superior to that available in either Pagemaker or 
JustText. The program is more traditional but now includes a 
preview mode that shows what the printed page will look like. 
This baby is expensive at $750. FTL is located in Toronto, 
Canada (416) 487-2142. 

Adobe has also jumped into the desktop publishing race 
with it's first user application. The makers of Postscript an- 
nounced the Adobe Illustrator, a drawing and paint program 
designed from the ground up around Postscript. What is really 
exciting about this product is that you can scan documents, then 
use that scan as a postscript template, and dump the bit map 
jumbo for a fine art postscript rendition of the scanned image. 
This should be a must tool for anyone using scanners. (415) 852- 
0271. 

$10,000 Phototypesetter? 

One thing missing from all this desktop publishing activity 
is a low cost phototypesetter. I discussed that problem with the 
people at the National Association of Desktop Publishers and 
we agreed that such a product could be built. The specifications 
we decided on were: 1200 dpi phototypesetter with postscript 
and Appletalk compatibility for under $10,000 or about one third 
the cost of the Allied Linotype L-100, which is presently the only 
Mac phototypesetter available. The postscript RIP is available 
from Adobe. All we have to do is find a marking engine of that 
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resolution that can stop and start in the middle of a page as 
information is received from the postscript engine. Anyone 
wishing to help in the design and/or construction of such a 
prototype are invited to contact MacTutor at (714) 630-3730 or 
the NADP at (617) 437-6472. 

New Hardware 

The hard disk wars are heating up again. The favorite 
configuration at the show was a 40 meg hard disk with a 40 meg 
tape unit. Such 40/40 units were introduced by Mirror Tech- 
nologies and SuperMac Technology. SuperMac is also market- 
ing a stand alone tape unit for those of us who already have Data 
Frame (or other brand) hard disks. Just last week I was complain- 
ing that my 20 meg disk was too full. Now, one week after the 
show, my 40 meg disk is up to 32 megs! What is a body supposed 
to do? Anyone make a good reliable 90 meg drive? Now if I can 
just avoid a fatal crash until the tape units are ready to ship... 

An alternative to disk and tape is a new bernoulli drive from 
Bering. Nicknamed Totem, this box is much nicer than the 
previous bernoulli drives. The removable bernoulli disks look 
just like Mac disks only bigger. They each hold 20 megs in a 51/ 
4 inch configuration. The most popular configuration will proba- 
bly be the 20/20 where you get two removable 20 meg bernoulli 
disks. The only problem with this design is that the ease of 
backing up will mean you'll want to use lots of bernoulli disks and 
at $120 per disk, that could quickly cost as much as the drive 
itself! 

If you want to learn about networking, get a hold of the 
Kinetics catalog. That's right, their catalog of networking prod- 
ucts has lots of useful information about the problem of network- 
ing computers together. The principle products include solutions 
to the Appletalk to Ethernet, Appletalk to VAX/ VMS and 
Appletalk to Unix networks. The VMS solution is provided by 
Alisa Systems AlisaTalk written by Bob Denny. This is a true 
file serverthat turns the VAX machine into a Macintosh disk icon 
on the desktop. The catalog discusses a number of third party 
networking products and how they work with the Kinetics 
FastPath hardware that provides an Appletalk to Ethernet gate- 
way. Considering how little there is on networking in general, 
this catalog is a great service to anyone needing to connect Mac 
to the real world of big computers. Call (415) 947-0998. 

That does it for the Expo. It was truly the best one yet and 
really showed that Macintosh has arrived as an accepted product 
in all areas of the marketplace, especially business. In fact, there 
were so many three piece suits walking around, you had to pinch 
yourself to remember this was a Mac show! If only Jim Warren 
would come back on his roller skates again like the old West 
Coast Computer Faires. Now those were the days the style of 
MacTutor was made for! 
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Nosy News 
A New Debugger for the Mac 


Nose to Nose 


V 


Introduction . -D- File Edit Display Stops Go Misc Srch Tables 


Steve Jasik 
Famous Mac Guru 


M MacTutor Contributing Editor 


MacTutor Vol. 3 No. 4 


T_FCBSptr_@2874 -Notes- 


lenFCB_buf : $0EB2 
openF i les :FCBrec 
[ 11 = ҒСВгес. 92876 
2) = ҒСВғес 92804 

3] * ҒСВгес. 82932 

41 = ҒСВгес. 2990 

5] = ЕСВгес. Р29ҒЕ 

= FCBrec_®2A4C 
?] = FCBrec..£2RRR 
8] = ҒСВгес. Р2В08 
9] = ЕСВгес. 92866 


After 6 months of hard work I 
was gratified to see the positive reac- 
tions of fellow programmmers who 
stopped off at the Mactutor booth (at 
MacWorld in SF) to watch my demo 
of "The Debugger". Had the reac- 
tions been any more positive (or le- 


9 p NoEject BOOLEAN FALSE ; for Eject & Off-line 
thal?), Más would have needed an on OrMstrBik INTEGER 2: master directory block in volume 
site field hospital for the treatment of Э4Е FcbSPtr pT-FCBSptr “ЕЗІНЕ ; file contro! blocks 
352 DefUCBPtr UCBPtr “UCB_B677A default volume control! block 


blown minds! I was demoing "The 


ы и ‚ 356 UCBQHdr QHdr ; VCB queue сас 

Debugger" оп a Big Picture by E- OF lags pem o p 
. H ч 

Machines, and the problem program is aco 
(the one being watched by "The 360 FSBusy INTEGER 0 ; non- zero when FS is busy 

" А 362 FSQHead QElemPtr NIL ; first queue command 
Debugger") was running on the Mac 366 FSQTai | QE emPtr NIL ; last queue element 

imi 36R HfsStkTop Ptr €003EC2 ; Temp location of pointer to top of 

SCICON: I should have a similar setup 36E HfsStkPtr Ptr €003E1R ; Temp location of HFS stack pointer 
available for the Micrographics 372 WOCBsPtr Ptr 6003738 ; Working Directory queue header 


376 HfsF lags 


monitor by the time you read this. 


Byte 


“T_FCBSptr = Record (3762 леу 
( 0) lenFCB.buf : Word 
( 2) openFiles : RrrayL1:401 of FCBrec 


"Systen" 


"The Debugger" | 
"RoM.aci" 
"Tutorial" 
"Tutorial" 


р Internal HFS flags 


Fig. 1 System Globals De-Mystifled 


Why and How 


The current version of TMON has been with us since May 
85, almost 2 years (the 585 in V2.585). Given that they didn't 
seem to be doing much to improve it, I started work on a 
debugger. I considered this a natural extension of MacNosy. 

One of my objectives was to use the standard Macintosh 
interface. My first task was to figure out how Switcher worked. 
Then “The Debugger" could run in its own Heap Zone above 
BufPtr (the Last Byte Address of memory that an application 
may use). With Nosy and the Switcher internal documentation I 
was able to disassemble Switcher and understand its Launc- 
hSubTask procedure. As it is a non-trivial exercise, I'll leave the 
details for some other article. If you can't wait, disassemble 
RunDbgr, which Launches "The Debugger" into its Heap Zone. 


Some Goals 


A debugger can be viewed as an extension of a Problem 
Program (PP). It must be able to interactively display informa- 
tion about PP's state, change the environment, and create oppor- 
tunities for transfers of control so the user can inspect the PP's 
behavior. 

А primary goal is to present information in formats that are 
"natural" to the PP and allow us to easily recognize any under- 
lying patterns. 

Another goal is to take advantage of the Mac interface so a 
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userof "The Debugger" can selectan item to be inspected in detail 
by clicking on it and issue the command "show me the structure 
of" the selected item. In Nosy and "The Debugger" this is 
implemented as "Cmd-space", but more about this later. 

The above goals are desirable for any debugger, but one that 
runs on the Mac needs to take into account that the Mac is not a 
mainframe. There is no clear separation between the PP and the 
Mac OS. Stated another way, you are "in bed with the Mac", and 
any false move may be dangerous to your health. The primary 
reasons for this situation are the complexity of the Mac interface, 
the lack of memory protection, and the lack of validation of 
parameters to Trap calls. Other than time and experience, which 
bring understanding, little can be done about the complexity of 
the Mac interface. The lack of memory protection can be solved 
by an add-on hardware board or chip, but most of us will have to 
live without this protection for a while. The lack of validation of 
Trap parameters can be eliminated during the debugging phases 
of a program by applying the Trap Discipline program as imple- 
mented by Steve Capps or as available in the various debuggers. 

Given all of the above, I created the slogan "Beyond Disci- 
pline, Into Bondage", and set out to implement it in "The Debug- 
ger" in a way that would automatically place a larger set of 
constraints on the PP. "The Debugger" tries to catch a larger class 
of errors before the program runs amuck and forces the program- 
mer to find a suitable part of his body to scratch to stimulate 
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mental activity. 
Some of the other goals are that 


"The Debugger" run on machines CU MM 


== -Тгар Call- т — 
"АВЕС CopyBits ; (srcBits,dstBi =: Ві Мар; srcRect,dstRect:Rect; mode: INTEGERIC 


‚ К srcBi ts 
with a 68020 CPU chip (present and baseAddr : @014C9C SSS -Registers- 
future), and that it take advantage of bape ae EAE UR РС= @0000ECBA SR= ttSm.ooo. . .xNzVc 
bigger and multiple screens as they dstBi ts re. арто. Н Te me 
become available. basefiddr : @1FA700 0 EE32 1DSFFFFD 5Е40 3021 '^e0!' 
rowBy tes 9s ! €CO5O 412ЕбЕ FFFF FFFF °....° 
pounds ac oci 2 Ғ80000 - - - - 0010 0001 
Displaying Information in srcRect : 00 16 16 3 ECDO2 4EF90000 0000 0000 
a Human Readable Format жи йыр фи ы айсы 4 ФҒС — 4168C8 0000 0000 
mode : srcCopy 5 ЕССЕО ЕССОС 0000 0000 
naskhgn ; NIL б ECID2 ЕС5Е2 0000 0000 
"Inside Macintosh" uses Pas- ?___ЕС102 __ЕСУЕ2 0000 0000 
cal to describe the variety of data Fig. 2 The Register Display 


structures which are part of the Mac system. I first created the 
command, "Fields of" or " Cmd-?" to display the structure of a 
record name. Taking this concept further, the notation 
"Type@nnnn" is interpreted by the "Fields of" processor as а 
command to display the values of the field of the record. In order 
to avoid excessive typing in "The Debugger", "Fields of" was 
further extended so that clicking on an address results in a simple 
Hex/Ascii dump window of the contents of memory beginning 
at thataddress. While developing all this, I decided to de-mystify 
the System globals (the area from $100 to $1400) by displaying 
them in their natural formats. Figure 1 is a partial display of 
them. The FCB window shows the results of clicking on 
"T FcbsPtr(2nnnn". Other structures that you may find interest- 
ing to look at result from chasing the "uTablePtr" and "Win- 
dowList". See fig. 1, System Globals. 


-Stack State- 


at RDODR--Name-------- Calls--- Frame-Rddr--Size 


R122 BTST 


410508: 


Fig. 3 Stack Frame 
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The Register Window 


Central to any Debugger is a display of the Machine registers 
and other interesting quantities. As you will note, not only does 
it display the values of the Address and Data registers in hex, but 
also the value of the address pointed to by the Address registers, 
and the values of the Data registers in Ascii. I added a display of 
"curPort", the current drawing port to the window, as we tend to 
occasionally draw to the wrong port. See fig. 2, Register Display. 


The Stack State 


Somewhat more interesting than the Registers display is the 
state of the Stack. It gives us an idea of what the program was 
attempting to do when an error occurred. The "znnnn" in the 
leftmost column is the machine address at which the call oc- 
curred. Selecting it, and pressing "Cmd-D" will bring up a display 
of the procedure, and position it to the point of the call. The other 
columns contain the name of the calling routine, the name of the 
called routine, the address of the stack frame, and the size of the 


=4104РС rPR.81?«12 — bytes in use = IFO local stack frame. This last number is useful for finding "piggy" 
z41014E TBtrp34 rPR_81? EC884 И p ; 
=006F52 NewHandle TBtrp34 EC8BO routines. They have large local activation records, which may 
=401FB4 R_emulat rPR_1601 EC8B4 contribute to stack overflow. Мое that I use a proprietary 
=4 16856 rPR.1362 -NeuHandle ЕСВСС i : А " ing 
2415716 FPR 1333 “ӘН 1262 ЕСЕП nir 2. ме display that does not involve "chasing 
=416A9A Teldle rPR_1333 ЕС804 . ее LZ. 5, Stack Frame. 
zOOEE?R CURSORRD -Teldle ЕС90С 
zOOEFOR MRINEUEN CURSORRD EC924 10 
-00Ғ236 Tutorial MA | NEVEN ECR64 13C Asm Windows 
rPR. 817? 
Ideally, one wants to debug a 
eECBBO 410152 rPR.B1? POP.L Al program by looking ata display of 
4104EC: 472 eEC8B4 6F S58 MOUEM.L D3-D?/R2-R65,-(R?) the source code. In the current 
4104FO: 112 410152 PUSH.L Al t 
4104F2: 002 105 MOVE.L 00,02 state of the Mac world you can 
6118 CBOO HOUER.L TheZone,R6 only do this with LightSpeed™ 


Pascal. Further-more, we don't 
have source code for the ROM, 


410502: mda.3 BSA rPR. 814 which was coded in assembly 
| 410504: BMI rCO. 223 " s 
410506: MOVE.L 02,00 language. “The Debugger can 


display a disassembly window in 
two formats. The first is the stan- 
dard Nosy format. The second, 
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-Trap Call- 


ABAD PtinRect ; (pt:Point; г: Весі): BOOLEAN 
curPort: gp8F?RR "Tutorial Text" 
fun Result : TRUE 
pt : 64 180 
: 0 4 296 480 


CURSORRDJUST 


BEQ.S 
Fig. 4 The Asm Window 


used in Step mode, leaves an execution trace in the window. 

InFigure4, the numeric fields are (leftto right):, the proc rel 
address of the procedure, the mrs (mode, reg and size) of the 
instruction, the ea (effective address) of the instruction, and the 
contents of the ea prior to execution of it. By displaying the data 
this way, we gather information in one window, that one would 
have to create many windows to observe. "Observe" windows 
are not implemented in "The Debugger" as of this writing, but 
they are high on my to-do list. Other things you may notice about 
the Asm windows are that all referenced procedures have names, 
not just the ones in the same segment, and that where data might 
be an ASCII character, the equivalent is listed on the same line. 
The line that is about to be executed is hilited. 

To change the program counter, one may hilite a line (or an 
address) and then select the "Set PC" command. Breakpoints are 
indicated by a * in column 9 of the window. See fig. 4, Asm 
Window. 


WatchPoints and ROM Bkpt's 


A watchpointis an area of memory that you want to monitor 
to find out who is modifing it. In order to do this in software, a 
debugger must check the area being watched after the execution 
of every instruction. In Macsbug (SS command) this slows 
program execution by a factor of 50 to 100. This has a number 
of undesirable side effects. The mouse and the keyboard are 
unusable. Also, itis so slow that one sets a watchpoint, and takes 
alunch break. This tends to limit the usefulness of the command, 
as one lunch per day is sufficient for most of us! 
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I managed to implement watch- 
points in such a way that the slow- 
down is by a factor of 4. This elimi- 
nates the undesirable side effects. 
Thus, the command becomes much 
more useful in a wider variety of 
Situations. 

Breakpoints are a normal part of 
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A Bit of Bondage 


On "real" machines, where much of the arithmetic is done 
in floating point, it is standard practice to "background" or preset 
memory to some suitable quantity whose use in a calculation will 
cause an interrupt. This presetting quickly flushes out the use of 
variables prior to their definition. "The Debugger" optionally 
presets stack frames of procedures on entry. This, and other 
advanced features, help you find programming errors quickly. 


Out to Lunch Programs and Jump Tracing 


One of the things that makes debugging on the Macintosh 
difficult are programs that grab an address from the stack or some 
other place and jump off into the wild blue yonder. Reconstruct- 
ing the chain of events that led up to this abberent behavior is a 
non-trivial task. On machines with a 68020 CPU help is at hand 
in the form of a Trace mode that interrupts only on change of 
flow. I have implemented a Jump tracing mode for such situ- 
ations which keeps a record of the last 10 jumps that the program 
took, and displays it on entry to "The Debugger" in the '-Jumps- 
" window. 


Trap Intercepts 


Rather than select Mac trap calls to be intercepted by their 
trap number or range, "The Debugger" lets you do it by suite, and 
name within the suite. A suite is a related set of trap calls. You 
may independently select to break on combinations of entry to, 
exit from, user or all calls to a given Aline trap. In addition, the 
parameters of the trap call are displayed in their "natural" format 
in the "~Trap Call-" window. An alternate way to set or clear a 
trap intercept is hilite a trap name (underscore optional) and 
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Fig. 5 The Trap Call Window 


select the "Set Intercept" or "Clear Intercept" commands. See fig. 
5, Trap Call Window. 
Heap Dump 


What's new in my Heap Dump? For one thing, I recognize 
a few more heap object types, such as patches and TeRecords. 
The other is that in columns 4 to 12 there is a code of the form 
"xx@nnnn" that you can click on to bring up a structured display 
of the block's contents. Note that Cmd-shift-space brings up a 
Hex/Ascii memory dump window. As the display is text based, 
you can search it with the Find command, etc. Also: a bullet in 
column 1 marks a locked block, and a blank in column 2 marks 
a free block. See fig. 6, Heap Display, followed by fig. 7, showing 
a text edit record contents. 


Set Mem Size and Switcher problems 
Does your program blow up when it runs in 400K or some 
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Fig. 6 The Heap Display 
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other memory size under Switcher? The message you get from 
Switcher that your program was terminated by a System Error is 
not very helpful! So I added the "Set Mem size" command so that 
you could easly test your program under control of "The Debug- 
ger". You use the command prior to launching the PP in "The 
Debugger". The command was put into immediate service when 
I spent a day chasing down memory-related blowups in Nosy 
running in a 500К partition. 


BreakPoints - Any Time, Any Place 


"The Debugger" allows you to specify an "unlimited" 
number of breakpoints (the Surgeon General has determined that 
Breakpoints are subject to memory limits). Another neat thing I 
did was to patch into. LoadSeg and _UnloadSeg so you can set 
a breakpoint anywhere in your program without having to worry 
about the segment being in memory. This is useful for your own 
programs, and doubly useful for cracking heavily protected 
programs that have code to disable debuggers. You can set a 
breakpoint at a particular location by bringing up a display of the 
procedure containing the location, hiliting the entire line or just 
the address, and selecting "Set Bkpt at". Another way to set a 
group of breakpoints is to select a list of names in the "-Code 
Blks-" browser window and select the "Set Bkpt at" command. 
This will cause the program to break into "The Debugger" on 
entry to the procedure. 


GNE Intercept 


TMON has a command called "Trap Signal" which lets you 
enteritona GetNextEventcall. My implementation lets you type 
“option-\" to enter "The Debugger" on 
exit from a GNE call. You can also 
select to break on a specific event 
type. For example, you сап study how 
a program processes window activate 
events. This command is a special 
«0236» case of conditional Breakpointing. 

Miscellaneous Features 

Like Nosy, "The Debugger" has 
an on-line help facility, and full text 
file handling facilities (open, close, 
delete, edit and search). It has com- 
mands to re-Launch an application, 
boot the system, and unFreeze the 
Mouse. Last but not least, it shares the 
Tables menu with Nosy, so the IM 
record definitions, Trap calls, error 
numbers etc are on-line. 

The Future of The Debug- 
ger 

Unfortunately I cannot code fea- 
tures into a program as fast as we can 
think of them. There are a number of 
features which are planned for "The 
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Debugger", but are not coded yet. By the time you read this, the 
following features should be added to it: 

* AnObserve window to watch the values of variables; 

* Acalculator window; 


* 


Conditional Bkpt's with Print clauses; 
Trap discipline; 
Facilities to record the values of variables; 
Ability to feed it files of user defined record types; 
By this summer, in cooperation with some of the compiler 
makers, true source level debugging should be available on the 
Mac. 

Nosy - Present and Future 

Nosy is up to V2.55. T ve cleaned up the handling of ".map" 
files so they can serve as input to "The Debugger". I've also 
enhanced case statement recognition, including code to recog- 
nize and process case statements generated by LightSpeed™ C. 
More significant to most of you is that Nosy will now have a real 
manual!! Nosy and "The Debugger" will support the SE and the 
II. For further details on updates and ordering information, check 
out my advertisments in MacTutor in this issue and over the next 
few months. 


* + 


Late News Flash! 


The Debugger now reads the symbol table in a LS C project file. 
One may transfer directly from LS C to the debugger, launch the 
project file and have access to all the procedure names and global 
variables in the program. Thanks Think! 


< — 


Sel 


GED, 
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Advanced Mac 'ing 
Getting Serious About MPW 


Introduction 

We had all just hunkered down into our seats with some 
fresh coffee when The Boss wandered in to get the department 
meeting going. He had been talking a lot about "improving our 
productivity" lately, and word was going around that we were 
soon going to be switched from the Good OI' Lisa to MPW. 

"Alviani", he started off with (a bad sign for sure), "you've 
got a lot more experience with different environments than most 
of the guys here" (and alot more gray, I thought to myself), "and 
you spend your time building tools for the rest of the staff, so I've 
decided to let you be the first to switch over to Apple's new MPW 
system. I want you to figure out how to actually use the dang 
thing, which the manuals sure keep me from finding out. Find the 
bugs, build procedures, squeeze the daylights out of it..." 

Great, I thought to myself above the rising crescendo of 
patriotic brass band music, I get to play human mine detector...... 

MPW (which stands for Macintosh Programmers’ Work- 
shop) has recently become available to the world thru APDA, 
and, like most revolutions, has polarized most people into "егіс 
and ‘agin it' camps. I have no intentions of trying to carry out 
religious conversions in this article; instead, I'd like to spend 
some time clarifying the (often excessively terse) MPW refer- 
ence documentation and providing some "hints and tricks" ma- 
terial on how to use it. 

I should state before going any further that the documenta- 
tion that comes with MPW makes no pretense of being anything 
other than reference material, which is not terribly unreasonable: 
the MPW and assembler manuals are already 2.5" thick and 
weigh 5 lbs. The Pascal and C manuals are each about 1" thick. 
Thus, if you have the entire package, there's 4.5" - 5" of reading 
ahead of you (add another 1" for MacApp). Including tutorials for 
each component would require Apple to ship MPW by truck. 
(Besides, I'd have a much worse chance of getting Dave Smith to 
print this article if there were first-rate tutorials included...) 

Also, let me emphasize that I assume you have the MPW 
documentation toreferto when reading this - Iam trying toclarify 
the reference material, not repeat it. I am working from version 
1.0, APDA draft of October 3, 1986 (the latest shipped from 
APDA at the time of writing). 


What is MPW and who is it aimed at? 

MPW is an easily extensible in nvironment, in- 
spired by the famous UNIX programmers' workbench. The 
Think Technology products, Lightspeed CTM and Lightspeed 
Pascal™ , are also integrated environments, although language- 
specific ones. 

The MPW environment, like the UNIX workbench, is 
command-line oriented, with the ability to specify options on the 
command lines, etc. While this may seem like a reversion to a 
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more primitive time, there are several advantages to this ap- 

proach when programming: 

(1) The method of executing commands is quite flexible. You 
can select any text in any window (using standard editing 
methods) and simply execute it. The "Instructions" files that 
come with the various language packages, for example, use 
this approach by embedding commands in the explanatory 
text and telling you to select and execute them to build a 
specific program. 

(2) Unlike UNIX, the worksheet that you usually work from is 
a normal text window. This means that a number of com- 
mands can be typed and checked before execution. Com- 
mands that you need repeatedly are simply left in the 
window and re-selected when needed again. If you need to 
execute a command repeatedly with a set of run-time 
options, they are set once when typed on the command line, 
rather than being selected each time from the menu bar. 


Shell variables and command files allow MPW to be totally 
and precisely configured for a specific purpose, and changed 
easily when needed. User-built Tools, properly configured, have 
all the freedom of those shipped with MPW, and allow it to be 
extended virtually indefinitely. 

MPW is aimed at larger, multi-file projects, rather than at 
quicky, "one-off" programs, where it would be overkill. There is 
definitely a learning curve associated with MPW, but the results 
allow you to automate most of the mechanics of working with 
large projects, freeing you to concentrate on the actual programs 
(which is already complex enough). In addition, once you've 
gotten the hang of writing command files, etc., there is a certain 
glee in watching them execute that's like watching a piece of 
Victorian clockwork in action! 

In short, MPW is rather complex for somebody trying to 
learn the Macintosh, but is extremely nice for somebody already 
familiar with the Mac. Once you've worked with MPW for a 
while, it becomes quite comfortable, and, like an old slipper, fits 
better the longer you wear it. 


Good and bad points of MPW 

There are plenty of both, as this is a big product (13 400K 
disks and 1675 pages of documentation if you get all compo- 
nents). 
Good Points: 
Totally configurable. The combination of command options, 
command files, tools, and the ability to build custom menus 
allows you to set up MPW exactly the way you want for any 
purpose, and to change it at any time. 
Excellent help facilities. While they won't replace the documen- 
tation, it does a good job of explaining exactly what options are 
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for each command, the meaning of the various special characters 
used in regular expressions, etc. You can enter Help commands 
to get a list of commands available, each followed by a comment 
about their function; typing Help before a specific command in 
the list and hitting the enter key then gives you the details for the 
requested command. 
Powerful programming facilities in the shell. The shell includes 
a complete set of control structures so full programs can be built 
in the command language. Looping, branching, and begin-end 
structures are provided; when combined with variable expansion 
, dialog boxes, etc., quite powerful tools can be built quickly. 
Powerful command files possible. Алу text file can be executed 
as a command, so that complex sets of commands such as 
mentioned above can be put into "macro" files and executed 
whenever desired, justas if they were regular commands built in. 
These, of course, can refer to other command files, so that 
capabilities are almost unlimited. 
The entire external environment is available to tools. This means 
that options can be put in variables that are globally available, for 
example, and accessed by a tool. This can make life easier in 
some situations. 
The assembler is extremely powerful. The macro capabilities of 
the assembler are explicitly modeled after those in the IBM 360/ 
370 assembler, which is widely regarded as being absolutely 
first-rate. Sophisticated parameter usage, code optimization(!), 
string manipulation and conditional assembly commands are 
waiting for you. The ability to declare data structure templates 
in a way very similar to that of C or Pascal simplifies life greatly, 
and "object-oriented" features make it easier to work with 
MacApp or other object-type environment. 
Sophisticated compilers are available. While the Pascal compiler 
seems to still have a few bugs, the code produced is quite good. 
The C compiler also seems to produce excellent code. Both 
include the tools necessary to write desk accessories and MPW 
tools easily, without clumsy workarounds. The best environment 
around is worthless if the compilers aren't reliable or if they 
produce mediocre code. 
ns obj rien rogramming technol V 

programmer, Object-oriented programming is looking like a 
very promising way of handling large, complex programming 
projects (which includes 'most anything on the Mac, it seems). 
Estimates of productivity improvements have ranged as high as 
five-fold. By taking this technology out of the academic world 
and making it widely available, Apple should help Mac program- 
mers produce the best programs in the world at an even faster clip. 

king towards the f . The assembler, in particular, 
explicitly includes support for: 68000/68010/68020/68030 proc- 
essors, the 68881 floating-point math unit, and the 68851 paged 
memory-management unit, important considerations now that 
the Mac II is available. 
Bad Points: 
Complex to learn. Since there is a large command set, with many 
options possible for most commands, it takes a while to learn how 
to use it, and longer to learn how to use it well. 
Not as fast as some integrated environments. It does not appear 
to be as fast as the Lightspeed environments, which could be a 


694 


real problem when dealing with very large projects. 

Only reference documentation is provided. Which is why this 
tutorial exists at all. Much hacking and experimentation is 
required to learn to use MPW at all reasonably. 

А tool or command file can't aff variable defined outsi 
itself, This complicates the process of returning information to a 
caller. Work-arounds are usually, but not always, possible. 
Hints and Tricks 

Now that I've gone ahead with a mini-review of MPW, let's 
get down to some day-to-day details of using it that aren't 
included in the documentation. 

Programming the shell: This is the area that is most unlike 
the regular Macintosh environment. Using typed commands isn't 
totally alien to most of us, but the ability to build your own 
commands is limited in most systems. The closest experience for 
most people would be Red Ryder macros. 

In the following examples, the actual MPW commands will 
always be set ina Mono-spaced font, like this, so they аге easily 
distinguishable from the rest of the text (this is the same conven- 
tion used in Apple tech notes). 


е The mysteries of quoting. The use of the various quotation 
marks is not atall obvious from the MPW manual. Some rules 
of thumb about quoting are: 

(1) There is a definite hierarchy of "quote-mark strength". The 

ordering of the different quotation marks is: 


(a) ^... - execute enclosed statement and replace 
with it'S output. strongest 

(6) `...' - take contents literally (no substitutes) 

(с) дсһаг - take char literally within "..." 

(а)"..." - variable substitutions, etc. occur 

(е) /.../ and V...V -regular expression quotes. weakest 


(2) The various quotation marks, unlike parentheses, do not 
"nest". Therefore, you can only use one set of each kind in 
an expression, except for the "delta" form dchar, which you 


can use anywhere since it doesn't occur in pairs. That is, 
set ver "This is а "quote"" 8this won't work at all 
set ver "This is а d"quoted"" check out - shouldn't work 
set var ‘This is a "quote"' 8this should work 


which means that you may sometimes find it necessary to define 

a helper variable using the stronger quotes, then expand it inside 

weaker quotes. For example, see the section talking about the 

differences between a command built directly in a menu, and 
commands built in command files and executed from a menu; the 
quotation rules cause the major difference. 

e shell variables. While shell variables can hold simple abbre- 
viations or numeric values, there are other uses for them. A 
powerful use is to hold commands that can be used with 
variable expansion to assign the results of a dialog to a 
variable. For example: 

set ask "request 'Resource ID?'" 


set res " ` (аѕк) `" 
"request command 


The "soft quotes" are used in the 2nd line as a safety 
precaution. The shell will (1) replace (ask) with the request 


Üicommand - ask for ID 8 
"res := output of the 
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command [including the hard quotes], (2) execute the request and 

replace the command with whatever is typed in by the user, and 

(3) assign the command-replacement to the variable "res" (the 

command-replacement could include blanks, hence the "soft 

quotes"). 

This technique must be used when building commands as 
part of a menu item and you wish to use any commands that need 
hard quotes (there's an example coming up shortly). It is also 
handy when you have a group of command files that all need to 
use the same command; by exporting the variable containing the 
command, any command can use it. 

• Assigning selections to variables: This is well buried in the 
manual, and is not in the least obvious (thanks to Darin Adler 
for pointing it out!). The trick is to use command substitution 
with the catenate command, which can take a selection in a 
window and output it to StdOut. Thus, the technique is: 

set var ‘catenate "(window)".8" 

e Concatenation: While this is not spelled out in the manual, 
it turns out to be pretty trivial. The key concept is that any 
variable expansion takes place within the quotes before the 
assignment is executed. The following set of commands will 
define a variable (we'll use itas part of a path name), and then 
concatenate it in various ways: 


"define nm to the value ‘Partial’ 
"define directory pref ix 

nm now is "C:Sources:Pert ial" 
#nm now is "C:Sources:Partial.c" 


set nm Partial 

set pre C:Sources 
set nm "(Pre): (nn)" 
set nm " (пт) .с" 


e Insertion and deletion. As with other parts of MPW, there are 
usually several different ways to do these operations; the 
techniques differ according to whether the clipboard is used 
or not. To illustrate deletion, see fig. 1 below. 

* Building shell command files. Thisis one of MPW's greatest 
strengths. Shell command files allow you to extend MPW 
infinitely in any direction you care to take it. The Make 
utility, for example, creates a shell command file as its 
output; when that command file is executed, exactly what is 
needed to rebuild the application is carried out without 
further human intervention. 

Command files are programs, and need to be treated as such. 

You have variables, conditional execution, and powerful string 

facilities at your fingertips; it is also possible to debug command 

files pretty easily once you have done one or two. 
The easiest way to debug command files is to turn on the 

'echo' variable at the start of execution, using the statement: 

set echo 1 

but this can have strange effects, depending on how your com- 

mandis written. Especially when you are doing pattern searching 


deletion: 
cut selection "(window)" 


" (window) " 


replace selection '' 


and insertion: 
8selection must be INSERTION POINT for these to work! 
paste selection "(window)" 


Fig. 1 Deletion & Insertion 
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"delete to clipboard 
8"cleer", ignore clipboard 


Ясору from clipboard 


and replacing, the command should be written to execute in a 
different window than the one from which it was invoked 
(typically the target window), so that the output of the command 
echo doesn't interfere. A little experimentation will make this 
quite clear. Another useful technique, especially when trying to 
figure out exactly what the result of some regular expression is, 
is to "single- step" by using exit commands after each ex- 
presssion: see what happens, adjust until it works as desired, 
move the exit to the next command.... 

* Building your own help files for those command files. The 
help command can be passed the name of a file to use, which 
means you can write custom help files for complex command 
files if necessary. Using menu commands to build in the 
name of the help file could simplify matters even more. 
Fortunately, the format of the help file (which is an ordinary 
text file) is extremely simple: 

(1) Entries are separated by a line containing a '-' in the 1st 

column. 

(2) The 1st word on the line following a separator line is the 
key looked for by the help command. Everything 
between separator lines is displayed. 

* There are slight differences between commands added to 
menus and the same set of commands executed from a 
command file. The basis for these differences is the MPW 
quoting process. The syntax of the AddMenu command is 
not complex: 

AddMenu menuname itemname command 

which you'll notice implies that a single item follows the item 
name. Therefore, to include any useful command, it must be 
enclosed in quotes (normally the "hard quotes": '..'). Since you 
can't nest quotes, anything which would be enclosed in hard 
quotes in a command file can't be so quoted in the AddMenu 
command, but must instead be defined as a helper variable and 
expanded when the addmenu command is executed. 

Also, menu commands need to have their variables declared 
in the program doing the 'AddMenu' (usually User Startup) and 
then exported (due to scope rules) whereas command files can 
declare their own variables. Trying to declare variables within a 
command attached to a menu doesn't work. Such a command 
must use "external" variables, which must be exported from the 
defining program to be available to it. The normal way of adding 


a complex command to a menu from User Startup becomes: 
8 various other commands..... 

set x xxx; export x 

set y ууу; export y 

AddMenu NewMenu 'NewItem/n' à 

‘begin ;à 

set x (x) (y); echo (x) ;9 

end' 

Notice here that the actual text of the 
command is enclosed in the hard quotes, and 
that lines are always ended with 9-newline 
(nothing following the newline!!) so that each 
line of the command is concatenated to its 
predecessor, resulting in the required single 
item. 

е Regular expressions and navigating thru 
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the MPW universe. Regular expressions are how you maneu- 
ver through a file. It can take a while to get used to this if you 
are used to a position-oriented macro editor such as MEdit. 

The power of the MPW regular expression mechanism lies 
in the fact that you have the ability to both find a specified pattern 
of characters, and also to work relative to that location, in terms 
of lines and characters. You can either set the editing position 
(insertion point) to a given location, or set the extent of a 
selection. 

The fundamental approach to take in many cases is to use the 
pattern- matching powers for "coarse navigation" and then to use 
the positioning capabilities to set the selection or position ex- 
actly. Typically, you might search for "any string with $ on the 
left and . on the right", then extract "the selection after the $ and 
before the ." (getting the dollar amount from a formatted entry) 
although this example would be done in a single statement: 
find /9%/а:а/./ "(active)" "extract dollar value 

A common need is to copy an entire line, without the 
final newline. This is where the combination of pattern and 
positioning is the only easy way to do it: 
find /0?/:4/0n/ find from ist char up to the position 
"before the newline 

Another common need in command files is to be sure you're 
at the start of the current line before processing begins. This is a 
Situation where the fact that the positioning commands are 
evaluated with respect to the immediately preceeding subexpres- 
sion is important (and non-obvious); the following code first 
selects zero lines before the current line, then sets the position to 
zero Characters before it: 

find 1010 "(active)" "insertion pt @ start of this line 

Also, as mentioned in the documentation, regular expres- 
sions are used for parsing text. In combination with the tagging 
operator ® (used in the evaluate command as shown in its 
writeup) you can extract very particular pieces of complex strings 
for later processing. 

Pay attention to the priority of the operators used in regular 
expressions. Just as in programming in 'C', most expressions 
behave the way you expect them to, but the ones screwed up by 
the different operator priorities can be infuriating to debug! 

е Howto get the effects of common variables to a limited extent 
(which the shell ordinarily prevents). The fact that it is 
impossible for a command to affect a variable which was 
defined outside itself prevents the use of variables to pass 
information between commands. See the diagram below that 
illustrates the problem (modeled after the figure in the docu- 
mentation). 


It is possible to get some communications by using a scratch 
window toexchange info between command files. The technique 
is to maintain a string in a scratch window that can be worked 
with using replace, find, etc. In order to allow a number of 
command files to share a window without interfering with each 
other, I use the "keyword variable" approach: the string used to 
communicate between files is of the form keyword = value. 
Unique keywords pretty much ensure that different programs 
will remain isolated. (See fig. 3, next page.) 
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It is also possible, if there are only a small set of possible 
values for a "variable", to get some of the effects of a finite-state 
machine, by taking advantage of the fact that a replacement 


Set xx 10 


SES INA 
TUA 


Notice that the value 
of the variable is the 
same after the inner 
blocks of code have 
executed, even tho 

a variable of the same 
name was set to a 
different value in 

each block..... 


APTAS 


xx) is 10 
NER 
Fig. 2 Scope of common variables 


Operation returns a status that can be tested. If you are working 
witha "finite state machine" approach, you need 1 program block 
for each state (here in pseudo-code): 


-replace mode_n with next_mode 

-if the replacement succeeded, you were indeed in mode_n, 
and can do whatever you need to. End the program block 
with "Exit 0" so that the calling program can continue 
normally. 

-if the replacement failed, you were in one of the other modes, 
so fall thru to try the next one (the "keyword variable" will 
be unchanged by the attempt). 

-after the last state, reset the string to mode 1 so that you can 
continue the cycle again. 

Here is a complete command file for a glossary function 
that shows how it is done (state-saving code is in boldface): 


8 This is a 1-key glossary function 

8 To use: invoke it, and @ will appear. 

8 type the shortcut 

н invoke it again. 

8 The shortcut will be expanded in place 

8 Shortcuts that eren't found are simply deleted, 
# along with the @ and = bracketing them. 


"first-time setup test 

find о "(scr)"; find /selàs/ "(scr)" 
if (status) із 0 "test variable state 
echo -n "selas" > "(scr)" "make sure of starting 
state 

end 


were we іп ‘tag shortcut mode'? 
find О °(scr}° 
replace /seld=6/ se1*1 "(scr)" 


node 
if (status) == § 
replace $ E "(active)" 


exit д Чехії normally 
end 


*aove to 'expand' 
Swe were in "tag" 


®tag start of shortcut 
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write to "standard output" without worrying about the 
% replace failed - must have been in ‘expand mode' 


replace 5 — (active) " “tag end of shor tcut actual source of the data. The USER decides whether to 
( i nd Va ‘a/=/ "{active}" "find shortcut (without type at the keyboard, send in input from a file, or even 
set xx "catenate "(active)". 8^ "save selection in variable use a selection ina window! Similarly, the output can go 
find О "(gloss)" "stert at beginning of window to any window or file. It is this I/O redirection that allows 
f E | мо) "(01098)" "find shortcut you to use the catenate command to assign the contents 
1 Status; == А б ; 
copy /'/a:4/'/ "(gloss)" #сору expansion that followpeste of a window selection to a variable! (See figure 4 
V: /-/ "(active)" "replace shortcut (with tags) below.) 
else 
replace V: /=/ '' "(active)" delete shortcut (with tags) 
end 
echo “sel=§" > “(scr)” “back to ‘tag shortcut mode' е Auseful trick with the Count command. An example 
of the power of combining MPW tools is this com- 
Note, however, that the lines setting the state into ‘tag shortcut mode’ mand to provide line/character counts for all the 
will repl ntire contents of h window. If you are using the pascal source files in a project folder: 
scratch window for several strings, you should replace them with: Count ‘files H020:project:s.p" 
which will list the counts one per line. It works because 
replace $ "ѕе1=0" "(scr)" "set-up: just insert 


the output of the files command is substituted for the 


find о "(scr)" fback to 'tag shortcut mode' command itself before the Count is executed. 
replace /seld=1/ "ве1-0" "(scr)" "leaves all else untouched 


Command file examples 
e Pipes redirection of I/O, and conditional execution. These аге features | 
adapted from Unix which can be very powerful once they are under- | А fairly complex set of command files accompa- 
stood (the pipes/conditional-execution writeup is buried in chapter 3 | nies this article. One set creates a menu that allows you 
under "command terminators"). These features are all imple- tobuild Rez input files using interactive prompts for any 


mented by the Shell. 

In a true Unix system, a pipe can be either used to commu- 
nicate between commands or used as a "data area" to communi- 
cate between tasks while they are each executing, in a multi- 
tasking mode. Since the Mac is a single tasking system, MPW 
pipes are only available between commands, and are essentially 
anonymous files with implicit I/O redirection. Pipes allow you 
to combine several commands without having to worry about 
creating intermediate work files. A common use of this is to 
follow acommand such as files by another command to do some- 
thing with the list of filenames produced ("list all pascal files | 
count lines | sort into ascending order by linecount to impress the 
boss"). 

I/O redirection is one of the most powerful features of the 
MPW shell from a programmers viewpoint. Because of it, you 
can write your tools to simply read from "standard input" and Fig. 4 Shell Communication 


Calling Command File Scratch File resource type needed, to avoid the 


echo "sel-1" » "scratchfile" typically obscure syntax errors that 
caneasily creep in, and to make sure all 
the parameters are in the right order, 
etc. Another file implements a glos- 
sary function allowing shortcut re- 
placements of unlimited size that 
shows a technique for passing infor- 
Note: You can't write to the mation between command files, or re- 
Е _ "clipboard"; you must create the taining variable values between invo- 
Asi 2 /зеід-2/ д scratch file yourself. Any number cations of the same command file. 

I won't go into detail about every 
command file (having gotten a tech- 
nique functioning, I tend to work it to 
death), but there are some points worth 
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ЕНЕНЕ | 


Catenate Tool 


of "keyword variables" can occupy 
the same window if you're careful. 


Scratch Files 


going into as examples. Let's start with the UserStartUp file, 
where the process of adding menus begins: 
The basic structure I use when adding menus is as follows: 


Confirm 'Do you want menu x' 

if (status) == d 

begin 
set br 'BoundsRect (t,1,b,r)?' "for expansion later 
export br 850 nested file sees it 

"define more commands, etc. 
"НО20 : MPW : doRez" 

end 

end 


"yes I do 


"this has the AddMenus 


А command file is used to actually add menu items to keep 
the command file size under control and so that the menu is easy 
to change: I can simply change HD20 : MPW :doRez and re-execute it 
to update the whole menu at once. А few commands that are used 
in menu items directly are defined here. 

There is no fixed rule as to when a function can be imple- 
mented directly as part of an AddMenu command and when it is 
better set up asa separate command file, which is executed by the 
menu command. I simply put the more complex functions in 
separate files, to keep things simple and to ease debugging. My 
cutoff point is about a dozen lines. 


е The 'doRez' file, that actually builds the menu: This is a 
mixture of items that directly do something, and items that 
execute other files. Notice that in the "direct execution" 
items, every time we need command sub- stitution, it is done 
by variable expansion, due to quoting restrictions: 

set str "(st)" "expand st into request, execute, assign 

"the command output to variable (str) 

Also notice (in the definition for DITL, for example) that I 
don't use the "execute" command, but simply give the complete 
command file name. This is because the execute command 

: which we need here. The 

"getResAttrs" routine is a good example, by the way, of how 

MPW can be extended almost indefinitely: every resource-type- 

building command invokes it to get the ID# and other attributes 

of the resource under construction. 

* The "doAlert" command, that builds an Alert definition. This 
shows the general approach taken in most of the code to build 
individual Rez def- initions. Here is the actual command file, 
with notes following: 


echo "д/* "request 'Purpose:'" *9/" "what is definition for? 
"H020:mpw:macros:getResAttrs" ALRT 8(Note 1) 
set rr "'request 'BoundRect? (t,1,b,r)'*" 
8prompt for order of coordinates 
set st4 "'request 'St4- 
0K [Cance], invisiblelvisible,beeps|silent'"" 
"expand abbreviation for stage 4 
if (st4) =~ /#(00]#/ ; set s4 OK ; 
else ; set s4 Cancel ; end 
if (st4) =~ /#(lil#/ ; set 54 "(s4), invisble" ; 
else ; set s4 "(s4),visible" ; end 
if (st4) =~ /#(Bb]#/ ; set 54 "(s4),beeps" ; 
else ; set s4 "(s4),silent" ; end 


"(Note 2) 
8(Note 3) 


8C(Note 4) 


"use stage 4 values as defaults for following stages 
set s3 "‘request -d (54) 'St4- 
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OK |Cancel, invisible|visible, beeps|silent'*" 
set 52 "'request -d (s4) 'St4- 

ОК [Cance], invisiblelvisible,beeps|silent'"" 
set 51 "'request -d (54) 'St4- 

OK |Cancel, invisible|visible,beeps|silent'"" 


* output filled-in definition 
echo "a((rr)3),0t8/* rect *a/" 
copy 0:4/àn/ "(scr)" 
paste § "(active)" 
echo ",dtd/* DITL *9/" 
echo "(654),9%9/% stage4 *9/" 
echo "(63),9%9/% stage3 *д/" 
echo "(52),9%9/% stage2 *д/" 
echo "(s1) 9%9/% stage1 *9/" 
echo "д);" 


8Sboundary rectangle 
8(Note 5) get saved id 
"insert at current insertion point 
"explanatory comment 
"settings for each stage 


"finish up def inition 


Note 1: 

The subroutine not only gets the resource ID# and its 
attributes (defaulting to "Purgeable"), but also writes the re- 
source ID to a scratch window, from which it is retrieved later. 
Since it is customary for DITLs to use the same ID as their 
DLOGs and ALRTS, this avoids asking the user for the ID twice. 
Note 2: 

Normally, you'd only enter the 1st letter for each choice, 
such as OVS (OK,Visible,Silent). 

Note 3: 

This uses pattern matching to expand the abbreviation into 
a form Rez understands. I use character sets [Oo] so it is not case- 
sensitive. The «s bracketing the desired character sets are needed 
to allow for blanks, etc. 

Note 4: 

A classic example of concatenation, adding the new pa- 
rameter onto the existing string. Once this series of tests is done, 
the expanded form becomes the default for the following stages. 
Note 5: 

Here is where we get the DITL ID that was written out for 
us by getResAttrs from the scratch window. While we can't pass 
variables between commands directly, this works pretty well. 


е The "doMenu" command that builds an entire menu defini- 
tion. The actual program is listed later, being too long to 
include "in-line". This is a little different from other com- 
mand files in that it includes an inner loop used to build the 
definition of each menu item. The loop terminates if there is 
no title entered, or if the cancel button is pressed. Each item 
is output immediately once all the required information has 
been entered. 

Notice that as the very last act, the command deletes the ; 
following the last menu item. No ';' т ‘ls that finish 
a Rez definition. You will find that all the commands given аге 
careful about this, since Rez will object violently to extra semi- 
colons. 


Programming the Make Utility 


This is one of the most obscure and non-obvious, yet 
powerful and convenient, facilities in MPW. In some respects, it 
is the very heart of the system, since it can totally automate the 
process of building a program (or several programs at once, for 
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that matter) once the command file is set up properly. When you 
are dealing with programs that can exceed 100,000- 200,000 
lines (as we do where I work), Make isn't a luxury - it is an 
absolute necessity. Any program can, in fact, use Make effec- 
tively, since it can build everything automatically, including 
running the resource compiler Rez. (RMaker was notorious for 
often not cooperating with Make utilities, not having been 
written with them in mind). 

The aim of a Make command file (called a makefile from 
now on) is to describe the exact way in which each file in it 
depends on other files, and to provide Make with the commands 
necessary to rebuild it when necessary. These command can 
either appear explicitly in the makefile, or can be constructed 
from default rules you write into the makefile or from defaults 
built in to Make itself. The result is generally a tree structure: an 
application depends on certain object files, which depend on 
certain source files, etc. 


• Order of processing makefile commands. The order in which 
Make processes the contents of a makefile, and any default 
rules built into Make itself, is important, since it determines 
the order in which the output commands are executed. The 
basic principle is fairly simple: commands progress from 
-highest level" to "lowest level", in a "last-in, first-out" 
fashion. When the makefile is processed from start to end, the 
last-update time for each "target" file is checked; if any of the 
files on which it is dependent are more recent, then the 
commands needed to rebuild it are (essentially) added to an 
output queue. 

When the whole file has been processed, the queued com- 
mands are popped off to the output file. When the commands 
rebuild a fil written out in the 
same order you wrote them, The normal order of makefile 
commands is: 

? Directory dependency & default rules 

? "Rez" code & resources together into an application 

? Link object files into a code resource file 

? Compile all needed source files into object files 

? Any "independent" commands needed, such as for rebuild- 

ing a "dump" file 


e "Directory dependency rules" and the default rules. The 
documen- tation manages to utterly obscure how these inter- 
act. The aim is to provide a simple way to have all your object 
files in one folder, sources in another, etc. and still have the 
default build rules apply. 

The built-in default rules separate the path names into 
directory and file components, by using variable substitution. 
Directory dependency rules are needed to specify exactly which 
directories are to be used for source and output files when default 
rules are used to generate commands in the output command file. 
They are required if all of the files for a project (source, object, 
resource, etc.) are to be separated in any fashion and the default 
rules are used. For example: 


frank :mapper : obs: f frank:mapper: output f source 
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p.o f р 
Pascal (DepDir) (Default).p -o (TergDir) (Default) .p.o 


381] object files will end up as frank:mapper:obs: file.p.o 
ә11 source files come from frank:mapper: file.p 


• How to set up a makefile so execution terminates after the 
compilation phase if any compiles failed. The basis for this 
"conditional" capability is buried in note 47 about Make's 
makefile, but one qualification is not mentioned: the shell 
variable (exit) must be set to O to ensure that the command 
file aborts after any compilation fails. In fact, an even more 
convenient setup is possible with little effort 

The property of MPW when (exit) is non-zero ("continue 
no matter what!") that interferes with a clean conditional build 
ability is simple: recompiling or relinking an existing file only 
updates the existing file, rather than deleting it and writing a new 
copy on successful completion. This means that without precau- 
tions, a compile that fails will leave its object file in existance, so 
the link will spuriously complete...the Rez command will 
complete...and you don't really have a copy of the application! 

We are going to take advantage of the fact that the compilers 
return status values just like other commands do, in {status}. The 
approach is to begin execution of the generated command file 
with (exit) set to non-zero. Thus set, every compilation will take 
place, even if some fail. As each compilation finishes, the value 
of (status) that is returned is added to a "status accumulator". 

When the link step is about to begin, the value of the "status 

accumulator" is tested, and we exit if it is non-zero (because at 

least one of the compilations failed). Here is a fragment of a 

makefile that shows how it's done: 


Mapper . code (ob)Boxes.p.o and others...... exit 
(total) if (total) ғ @*abort if any compiles died L ink 
(ob)Boxes.p.o and many others...... 


(ob)Boxes.p.o f 
Boxes.p 


Boxes.p | Globals.p Pascal (Poptions) 
set total 'evaluate (total) * (status)" 


In the fragment, total must not be externally defined and 
exported!! The variables you are going to use must be totally 
local to the Makefile. If you read the documentation very care- 
fully, and experiment, you will find that any variables that are 
user-defined outside of Make are substituted when the output file 
is being written; that is, their values are written into the output 
file, rather than the variables themselves. This "build-time" 
substitution is why (Poptions) is usually defined in the user 
startup file and exported. 

So far, I have generally used explicit commands in putting 
together makefiles in this fashion. Default rules work generally 
in the same way, but require caution, as explained below. 

A segment using default rules looks very similar, except that 
there wouldn't be commands for each individual file: 


.р.о f p 

Pascal -o (DepDir) (Default).p.o (TergDir) (Default).p 
set total ‘evaluate (total) + (status) 

"Default applies to all source files 

по object file if compile fails 


699 


A major caution here: xtremel ful in ifyin 
your file dependencies!! It is a good idea to explicitly state that 
an output file is dependent both on its source and all included 
files. This is important with files that declare global variables, 
and may not be obvious (it wasn't to me!) 

While the linker deals with globals by name, offsets within 
records are numeric in nature. If you modify a record definition 
in an included file, for example, and the make file doesn't record 
that your source is dependent on that included file, the source file 
won't be recompiled using the new definition, resulting in inac- 
curate record offsets and very hard-to-track- down bugs! 

While default rules do work well in some circumstances, 
they must be used with care. Since I include files that define 
record types, I have gen- erally used explicit dependencies. This 
is more typing, but safer. 


* Make can carry ош any commands you specify - other things 
you can do with it beyond simple compilations. For example, 
a "dump" file is dependent on the files specified in the 
$LOAD directive that created/uses it. Should any of the files 
included in it change, it should be deleted so a new version 
can be rebuilt by the first module using it. This is easily done 
as follows: 


HD28 :obs: inst .dumpf ile Memtypes.p Other.p 
delete -y H029:obs:inst.dumpfile "force rebuilding 


e Howto time your build runs. The following sequence will not 
only build your project, but also time how long that took. It 
is set up to be a menu command: 


AddMenu Nifties "Мәке Project/O' à 
"begin; д 

directory HD29:Project ; 

open -n scretch; 

echo ‘date -s` › scratch; 

make -f makeproject > MakeOut ; 
MekeOut ; 

echo ‘date -s` >» scratch; 

echo "stetus-(status)" >» scratch 
end’ 


8switch to proper directoryd 
8create/open temp windowd 
write starting timed 

"create make command filed 
ЗасшаТу build projectó 
Bending time on new lined 
8final status, tood 


Other Components of MPW 


Rez and DeRez are very powerful programs: Rez is a 
complete replacement for RMaker, with considerably improved 
powers over the MDS version, such as conditional execution, 
variable substitution, etc. As in the Lisa environment, Rez 
normally includes the CODE resources from the linker into the 
final executable program file. 

Rez somewhat resembles C declarations, and it has "pre- 
processor" capabilities also similar to C. A major improvement 
is that you now have the power to define your own resource 
templates, so that it becomes possible to define complex re- 
sources in a very readable format, rather than in an endless stream 
of hex digits. 

In larger projects, the *include statement becomes very 
useful. The resources for a program can be split into a number of 
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different files (by type, for example) and the actual input to Rez 
becomes a short file including all the others. As usual, the 
advantage of this approach is that it is far easier to edit the 
individual files. 

Becareful of the difference between the * include and include 
statements (note that the latter does NOT start with #). The #-less 
form actually reads resources into the output file; that is how, for 
examples, pictures can be easily compiled in, without ever 
having been converted to hex. (See Note 1 at the end for the 
details) 


* Onthe subtleties of Rez syntax: There are a few points of Rez 
syntax that can be frustrating to master, most especially the 
placement of braces and semicolons. The manual is terse, and 
seems to avoid examples of the type of statement that will 
cause you the most trouble. The basic hassle comes in 
constructing arrays. À few rules of thumb that will help: 

(a) Switches explicitly include the case label, followed by the 
components of the entry within braces. For example, the 
definition: 
case Button: 
ebled; 
pstring; 

has two components (boolean and pstring) that actually are 

defined by you. The format of the entry that is fed to Rez is: 
Button (enabled, 'OK!); 

(b) Arrays are enclosed by an outer set of braces. Each element 
of an array is separated from the next by a semicolon. Each 
element can consist of any number of pieces separated by 
commas. No semicolon before the last brace! For example: 

( stert of array 

1,2,3; 3 pieces, element #1 

4,5,6 З pieces, element #2 (note no semicolon!) 
) end of array 

(c) Remember that points and rectangles, altho enclosed in 
braces, count as 1 "piece" in an array definition. 


booleen enabled, dis- 
key bitstring(7] = 4; 


DeRez is the complement of Rez (as if you couldn't guess!) 
: feed it a file containing resources and get back Rez input to 
recreate those resources. You would normally use the Apple- 
supplied resource description filesto provide the format informa- 
tion needed. 

Tools and the integrated environment: a great feature of 
MPW is the support given for building additional tools that can 
be automatically integrated into the existing environment. Using 
the facilities built into the environment can allow a tool to be 
extremely flexible and powerful without adding burdensome 
complexity for the programmer. 

The linker and library facilities: On the whole, the linker 
is quite powerful and flexible, but there are certain things about 
the MDS linker that are missing and would be kinda nice to have 
back (which I'll go into at the end of this section). 

In a move aimed (I think) at encouraging third-party ven- 
dors to at least provide a version of their development products 
that can integrate into MPW, Apple has published the exact 
details of the linker object-file format. This openness should 


© The Essential MacTutor, Vol. 3 


ensure that outside languages and packages gradually become 
available in the MPW world, allowing each programmer to mix 
and match pieces to get the set of features she/he wants. 

The linker does quite a lot of work in the processing of 
building a program. It has optimization features which can help 
to shrink a program by: 

-building the smallest jump table possible 

-eliminating dead code and data modules 

-changing the code it's processing to use the most efficient 
addressing modes possible (А5 relative between segments, 
PC relative within segments). 

Combined with the library program, a program can be 
shrunk quite a bit and the linking process made noticably faster. 
There isn't much to be said about actually setting up a link 
command; the manual is pretty clear. The main reason the 
process is straightforward is that you have almost no control of 
how a program is segmented in the link command. 

I have decidedly mixed feelings about the method used in 
MPW to set up the segmentation of a program. Pascal uses {$S 
segname ) directives embedded in the source files; C uses 
#define__SEG__ segname. This is designed to allow you to 
write related functions together in a single source file while 
putting them in different segments at run time. I have been used 
to the method used in the MDS/Consulair linker/librarian, which 
allows you to resegmenta program by simply changing the linker 
command file, rather than forcing you to recompile large chunks 
of the entire program after making source-file changes. It is 
possible to combine a number of segments into a new segment 
using the link command, but doesn't seem possible to rearrange 
modules into a different segment arrangement. When you start 
working with applications with LOTS of segments, this method 
starts to be somewhat bothersome. 

Another weak point of the linker is the map that is generated. 
There is simply not enough information in it to be really useful, 
and it is also incompatible with TMON. Specifically, it doesn't 
give the A5-relative address of the global variables, which is a 
crucial piece of information. 

Notes on the MPW Assembler: This is a genuine "down 
town" assembler, with features found in few other PC assemblers 
(heck, alot of mainframe assemblers could be envious!). Various 
neat features were mentioned in the overview at the beginning of 
this article. However, as in much of MPW, while the details are 
in the manual, the practical implications of them aren't. A small 
sample routine is included to demonstrate the points written up 
here; it generates 1 16-byte line of a memory dump for use in a 
resource editor, debugger, etc. 


е Templates. The major change for most programmers is going 
to be in the use of templates for laying out data structures; 
many people don't build complex macros, but everybody uses 
data. One great advantage of templates is that, used correctly, 
they can relieve you forever of having to calculate the sizes of 
stackframes, etc., manually. There are a few tricks for using 
these templates correctly. | 

(1) Use separate templates for parameters and stack frames. The 

parameter template should be an ordinary incrementing tem- 
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plate, while the stack frame template is a decrementing template 
set so that its origin is at the A6 entry. By doing this, you can 
define symbolic constants for the sizes of the parameters and the 
local variables, killing one common source of errors and frustra- 
tions. A sample looks like this: 


Paremeters RECORD 


0 incrementing template 
OutStr DS.L 1 

1 

1 

x 


83 VAR: where to put output 


Offset DS.L #2 VAR: offset in buffer 
Handle DS.L #1 handle to data buffer 
Size EQU use to adjust SP on exit 
ENDR 

name PROC stackframes should be local 
STACKFRAME RECORD (A6L ink) , DECR 

Parms DS Parameters right amount allocated! 
RetAddr DS.L 1 return address 

A6L ink DS.L 1 caller's Аб 

x local variables here 

War 1 DS.W 1 

1Уаг2 054 2 

War3 DS.B 26 

LocalSize EQU x use: LINK A6,*LocalSize 


ENDR 


(2) When you are using templates as shown above, note that the 
parameters are listed reversed from the Pascal order, starting with 
the last one. This is the only disadvantage of the technique, but 
is needed for it to work. 


(3) Don't worry about the addresses/offsets displayed in the 
listing file! They are corrected by the assembler when it has the 
entire template in hand, and the values shown later in instructions 
will be the correct ones. 


(4) Be judicious with the WITH andENDWITH statements. Like 
their counterparts in Pascal, they can be more inclusive than 
intended. 


(5) When you refer to entries in templates, be careful to "fully 
qualify" the names, or they will have the value of zero! Sizes, etc. 
should be used from "incrementing" templates. To adjust the 
stack on exit using the example above, use: 


ADDA "Peremeters .Size,SP 
-NOT- 
ADDA *StackFrame .Size, SP 


(6) I generally leave the warnings turned on. The assembler is 
quite thorough about detecting longer-than-necessary branches 
and calls, and the warnings let you shorten them immediately. 


• DUMP and LOAD commands. These are similar to facilities 
in the Pascal compiler. The aim is to store pre-digested 
symbol tables (mostly of the standard equates) in files to save 
the time wasted in scanning them during each assembly. 
Unlike Pascal, the assembler won't automatically create a 
"dumpfile" if it's not found; therefore, the trick is to have a 
very small assembly program that does nothing except dump 
the system equates to a file for everybody else's use. That 
would have only a DUMP command, while all regular files 


701 


would only have a LOAD command. Your makefile can be 
set up to cause the "dump application" to be run before 
anything else if you anticipate any changes in the equate files, 
or if you include some of your own files that may be fairly 
stable but not cast in cement. 

А few quick experiments on a 2-floppy system shows that 
using the LOAD command saves about 11 seconds per assembly 
as compared with processing all the equates. As in any big 
project, every little savings is precious. 


e Notes оп Macros: this is a somewhat random set of notes on 
working with the macro facility in the assembler; I haven't 
used it enough to be an expert, but there are a few simple 
things that can simplify life: 

(1) Labels in Macro expansions. It is not obvious that plain 
labels and (2-labels aren't always adequate, but the assembler 
simply copies them directly into the output, so there is the 
potential for "duplicate symbol" errors. The way to avoid this is 
to use the &SYSINDEX feature. This keeps track of how many 
times each macro has been invoked, and makes that value 
available in the form of a4-digit number. By including &SYSIN- 
DEX as part of every label in a macro, you can be certain that 
there will be no conflicts (at least until you've invoked the same 


macro for the 10,000th time...). Like this: 


BRA.S X1&SYS INDEX 
*various statements 


X 1&SYS INDEX тоге code...... 


which would be expanded to (on the first invocation): 
BRA.S X 1600 1 
*various statements 


X 160001 ‚тоге code...... 


(2) Use macros for generating large repetitive tables, Macro 


variables allow you to use indices in calculating table values, etc. 
Large lookup tables are often used for speed in time-critical 
applications (real-time games, for example) and are always 
tedious to enter by hand. 


(3) keywor increase macro readability. 
One of the strong points of the IBM 360/370 assembler was the 
use of keyword parameters. Altho the I/O macros were always 
very complex, the average programmer didn't find them intimi- 
dating because he provided most of the values using keyword 
parameters. It is always more reassuring to write "..,chan- 
nelz3,.." rather than worry if you are about to waste a half-day 
because the channel number should have been the 3rd parameter, 
not the 2nd. 


Notes on MPW Pascal: MPW Pascal is going to make a lot 
of people happy, I think. I am relearning my Pascal after a year 
as a full-time C programmer, so I am probably missing points an 
experienced Lisa Pascal programmer would catch, but here goes 
anyway. 

* Itis quite Lisa-pascal compatible. Тап informed by experi- 
enced Lisa Pascal programmers that MPW Pascal is essen- 
tially identical to it. This makes developers that have a heavy 
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investment in Lisa Pascal (such as Odesta) obviously very 
happy. Also, it should be a snap to convert programs written 
in TML Pascal. 

* The $LOAD facility increases speed considerably. This is 
powerful but somewhat picky. It does not seem to coexist 
well with the {$U} clause normally used to specify the source 
files needed in the USES clause. The following does work, 
however: 

(a) In the file STARTUP that is executed when the shell is 
started, the definition of the variable {PInterfaces} has the full 
path of the directory containing the sources. This definition can 
contain multiple pathnames, separated by commas. A definition 
might be: 

Set PInterfaces "{ MPW})PInterfaces:,HD20:Project:" 

Export PInterfaces 

(b) In combination with the above, the FILENAME for a 
unit must be the same as the UNITNAME, so that the automatic 
search for UNITNAME p will function correctly. Thus the full 
pathname for unit FileStuff is: 

HD20:Project:FileStuff.p 

(c) [have all the interface units packed together into a single 
load file, since they don't change: 

($LOAD HD20:Project:obs:ints.dumpfile) 

Memtypes, Quickdraw,OS Intf,ToolIntf,PackIntf,MacPrint, 

just using this saves an average of 50 seconds per compile after 

the first time thru which builds the load file! 

(d) After the name $LOAD clause above, use an unnamed 
{$LOAD} to end the "dumping" and start processing the rest of 
the unit files individually, so they can change as often as neces- 
sary. Thus, the final arrangement in the main module would be: 
($LOAD HD20:Project:obs:ints.dumpfile} 

Memtypes, Quickdraw,OS Intf,ToolIntf,PackIntf,MacPrint, 

(SLOAD) 

globals, otherUnit, anotherUnit; 


¢ It produces darn good code. Walking thru the output code 
using TMON or DumpObj reveals that the MPW Pascal 
compiler doesa very good job of optimizing its output. While 
compiler-generated code will almost never beat out hand- 
tuned code, MPW's overhead is very low. Commonly used 
variables are automatically kept in registers, using the WITH 
statement eliminates duplicate pointer-loading instructions, 
etc. Word has it that Apple is already working on improving 
the optimization processing for the next version of the com- 
piler. 

e It has object-oriented extensions built in. This has been the 
subject of several very good articles in MacTutor recently, 
and I haven't had a chance to play with MacApp yet, so can't 
say much, except that it looks like this may actually improve 
programmer productivity, once the concepts involved sink 
in. 


Brief Notes on MPW C: This is going to make the C 
programmers in the MPW world happy, without putting the 
existing C vendors out of business (for example, MPW C lacks 
the object extensions present in the Pascal package - you can be 
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the object extensions present in the Pascal package - you can be 
sure Consulair, Aztec, etc. are going to pick up on this!) 

It is based on the Berkeley 4.2 BSD VAX implementation 
of the Portable C Compiler, and was written by Green Hills 
Software; the library is based on the Standard AT&T Unix 
System V library. Since Apple has stated in public that it intends 
to make Unix available on the Mac (undoubtedly the open Mac), 
itistobe hoped thatthe same compiler will be used there - to have 
two slightly incompatible compilers put out by Apple for the 
same machine would be greatly insane! 


Various Notes 

Note 1: here's how you do go about putting pictures or other 
resources into never-compiled resource files for input to Rez, 
using ResEdit: 

(1) Start with the picture in the Scrapbook. 

(2) At the "file" level of ResEdit, create a new file. 

(3) Select the picture in the scrapbook, and copy it. 

(4) Paste it into the brand-new file. А РІСТ resource should 
be created. 

(5) Change the ID of the new PICT resource to something 
conven- ient for later use (starting with 128 isn't a bad 
idea ). 

(6) When you close the file, answer "yes" when it asks if you 


want to save the changes! 
UserStartUp - MPW Shell UserStartUp File 


Copyright Apple Computer, Inc. 1985, 1986 
All Rights Reserved. 


н This file CUserStartUp) is executed from the StartUp 
file, end can be used 

" to override definitions made in StartUp, or to def ine 
additional variables, 

" exports, end aliases. UserStartUp may also be used to 
define menu items, 

8 open windows, etc. The file should be located in the 
directory containing 

8 the MPW Shell. 


alias cd directory 

alias clone duplicate 

set ask "request 'Structure Level:' " 

export ask 

if "'request -d Pascal 'Pascal or C:'*" =~ /[Pplas#/ 
" (MPW)macros :Pas- Macros" 

else 
" (MPW)macros :c- macros" 

End 


set exit 0 850 confirm won't kill things on 'no' 
set scr "(MPW)scratch"; export scr 
open "(scr)" 
confirm 'Need the Rez menu?' 
if (status) == 
begin 
8 definitions to make nesting simpler... 
set br "request 'BoundsRect? СЁ, 1,6,г)'" ; export br 
set tit "request 'Title?'"; export tit 
set cid "request 'ID?'"; export cid 
set st "request 'String?'"; export st 
" (MPW)macros :rez macros" 
end 
end 
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set gloss (MPW)glossary; export gloss 
open "(gloss)" 
" (MPW)nacros:nifties" 


set PasMatOpts "-a -k -1 -n -r -e" 
export PesMatOpts 


Addmenu Nifties 'Formatted Hardcopy/9' à 

'Pesmat "(active)" | Print -f Monaco -h -s 9 -hf Times -hs 12 
-title "(active)"' 

Я  GetResAttr Utlity 

8 This gets the resource-ID, name, and 

# preload attributes for a def 

# Version 1.1 


set exit 0 

set rid "'request ‘Resource ID?'"" 

echo (rid) > (MPW)scratch tmake available for outside use 
set rname "'request ‘Resource Name?’ *" 


echo -n "resource à'(1)à' C(rid)" 
if " (rname) " 2 "nu 

echo -n ",д"" (rname}"9"" 
end 


confirm "Зей Attributes? (default: Purgeable)’ 
if (status) == 
begin 
confirm "SysHeap?" ; set sys (status) 
confirm “Purgeable?” ; set pur (status) 
confirm "Locked?" ; set loc (status) 
confirm "Preload?" ; set pre (status) 
if (sys) == Ø ; echo -n ",SysHeap" ; end 


if (pur) == 8 ; echo -n ",Purgeeble" ; end 
if (loc) == 8 ; echo -n ",Locked" ; end 
if (pre) == Ø ; echo -n ",Preload" ; end 
end 

else 
echo -n ",Purgeable" 

end 

echo ") a(" 


8 Interactive macros to build Rez definitions 

8 Frank Alviani - Tuesday, December 9, 1986 2:02:07 РМ 
8 Used with another language menu; no ‘top’ or 'bottom' 
8 macros needed 


AddMenu Rez 'Alert' '"(MPW)macros:doAlert"' 
AddMenu Rez 'Bundle' '"(MPW)macros:doBundle" ' 
AddMenu Rez 'Control' '"(MPW)macros:doControl" ' 
AddMenu Rez 'DITL' д 

‘begin; д 

set lclItm 1;0 

" (MPW)macros:getResAttrs" ОТТЕ; д 

echo "д(";д 

end' 
AddMenu Rez 'End DITL' ‘replace \;\ "дпд}дпд);дп" "(active)"' 
AddMenu Rez 'DLOG' '"(MPW)macros:doDLOG" ' 
AddMenu Rez 'FREF' '"(MPW)macros:doFREF" ' 
AddMenu Rez 'MENU' '"(MPW)macros:doMENU" ' 
AddMenu Rez 'SIZE' '"(MPW)macros:doSize" ' 


AddMenu Rez 'STR ' д 

‘begin; д 

" (MPW)macros:getResAttrs" "STR ",9 
set str "`(5{)`";д 

echo " 2" (ѕ1г)д"" ;9 

echo “д);";д 

end' 


AddMenu Rez 'STR'"' д 
"begin; д 
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" (MPW)macros:getResAttrs" "STR#";2 set tex ""(tit)'";0 


echo -n "9( ";д echo "a((rr)3),0ta/* (IclI tm) *д/",д 

100p; à echo " StaticText 9 ((onoff), д" (tex) à" 0);";0 
set str "`{5%)`";д set IclItm ‘evaluate (IclI tn) + 1`;д 
break if "(str)" == "S OR C(status) != 0); end' 
echo " д" (str)a";" ; ы 

end; à AddMenu Rez 'EditText' à 

cut \;\ "(active)" ; 'begin; à 

echo "anà)ànà) ;";à set exit 0;9 


end' 
AddMenu Rez 'WIND' '"(MPW)macros:doWIND"" 
AddMenu Rez '(-' '' 


AddMenu Rez 'Button' à 

'begin;à 

set exit 0:29 

set rr "(br)"; д 

conf irm "Enabled?" ; д 

if "(status)" == Ø ; set onoff enabled ;д 

else ; set onoff disabled; end;à 

set tex "(tit)"; 

echo "д((гг}д),д1д/* (IclItm} *д/"; 

echo " button à((onoff) , д" (text a"), ";д 
set IclItm ‘evaluate (IclItn) + 1°39 
end’ 


AddMenu Rez 'Checkbox' à 

'begin;à 

set exit 0;0 

set rr ""(br)'";9 

conf irm LL. 

if "(status)" 0 ; set onoff enabled ;à 

else ; Д set onoff disabled; “end; д 

set tex "*(tit}* 

echo "д((гг}д), (y (IclItm} *д/";д 
echo " Checkbox à((onoff), 2" (tex) à*3);" 
set IclItm "evaluate (IclItm) + 1° ;д 
end' 


AddMenu Rez ‘RadioButton’ à 

"begin; д 

set exit 0;0 

set rr ""(br)'";0 

conf irm "Enabled?";à 

if "(status)" == Ø ; set onoff enabled ;д 

else ; set onoff disabled; end;à 

set tex "(tit)" ";0 

echo "a((rr)a), 4. (1clItm) *д/";д 

echo " RadioButton 0{{onoff}, д" (tex) à" 9);";9 
set lclItm ‘evaluate (IclItm} + 1`;д 
end’ 


AddMenu Rez 'ControlItem' д 

‘begin; д 

set exit 0:29 

set rr "`{Ьг)`";д 

conf irm pect e 

if "(status)" ; set onoff enabled ;д 

else ; ; set onoff disabled; “end; д 

set спї110 "‘{cid}*";2 

echo "д((гг)9),9%9/% (IclItm) *д/";д 

echo " Control à((onoff), (cnt11D)) ; " ;9 
set IclItm ‘evaluate (1clItn) + 1°39 
end’ 


AddMenu Rez ‘StaticText' à 
"begin; д 
set exit 0;0 
set rr "(br)"; 
conf irm "Enabled?" ;à 
if "(status)" == 0; set onoff enabled ;à 
else ; set onoff disabled; end;à 
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set rr ""(br)'";à 

conf irm Enabled?” ;à 

if "(status)" == 0; set onoff enabled ;д 

else ; 5 set onoff disabled; ‘end; д 

set tex "(tit)" 

echo "д((гг) д), әк (IclItm) *д/";д 

echo " EditText à ((onoff), à" (tex)à" д);";д 

set IclItm "evaluate (IclItm) + 1`;д 
end' 


AddMenu Rez 'Icon' à 
‘begin; д 
set exit 0;0 
set rr "(br)"; д 
conf irm "Enabled?" 30 
if "(status)" == 0 ; set onoff enabled ;à 
else ; heh onoff disabled; "end; д 
set cnt1ID "`(с1їд)`" 
echo "à((rr)3), àta/* (len) *д/"; ; 
echo " Icon à((onoff), (cnt110)2);" ;д 
set IclItm ‘evaluate (iclI tn) + 10 
end’ 


AddMenu Rez ‘Picture’ д 
‘begin; д 
set exit 0:9 
set rr "`(г)`" 
conf irm "Enabled?" д 
if "(status)" == Ø ; set onoff enabled ;д 
else ; set onoff disabled; ‘end; д 
set cntlID "`(с1їа)`";д 
echo "à((rr)2),8ta/* (lclItm) *®д/";д 
echo " Picture à ((onoff), (стё110)9); “9 
set lclItm ‘evaluate (iclI tm) + 1`;д 
end' 


AddMenu Rez 'UserItem' à 
‘begin; д 
set exit 0;0 
set rr "'(br)**;8 
conf irm "Enebled?"; д 
if "(status)" == 2: set onoff enabled ;9 
else ; “Бей onoff disabled; “end; д 
echo "д((гг)д),д1д/* (1с11{т) *д/";д 
echo " UserItem д ((отоғ е) 2); "д 
set IclItm ‘evaluate (1с114} 4 E 1:9 
end' 


AddMenu Rez '(-' '' 


AddMenu Rez ‘Shift Item’ '"(MPW)macros:doShift"' 
AddMenu Rez ‘Adjust Width’ '"(MPW)maecros:doWiden" ' 
AddMenu Rez ‘Adjust Height’ '"(MPW)macros:doTaller"' 


* doBundle Macro 
н This interactively builds an ВМ Rez definition 
я Frank Alvieni Saturday, December 6, 1986 10:32:45 AM 


set exit 0 8so 'cencel' buttons not fatal 


" (MPW)nacros:getResAttrs" BNDL 

set sig “‘request ‘Signature? (4 chers2'"" 
set ver "'request -d 0 ‘Version Number?’ `" 
echo "0'(sig}d', dtd/* signature *2/" 

echo -n "(уег),9%9/% version *à/ànà(" 
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set ct 1 

set st 128 

loop 
set ty "'request ‘Resource type? (4 chers)2'"" 
break if C(status) != 0) OR C(ty) == "") 
set ct "request -d (ct) ‘How many?" *" 


set act "request -d (st) ‘Starting actual ID?'"" 
set st (act)'tupdate default starting ® 


set loc Ø "local ID 
echo -n "d'(ty)d', dta/* type *à/àn д(" 


loop 
if (loc) != 0; echo -n "," ; end 
echo -n " (1ос), (act)" 
set loc ‘evaluate (loc) + t" 
set act ‘evaluate (act) + 1° 
break if (loc) == (ct) 

end 

echo "д);" 


end 
replace V; X "дпд)д);дп" "(active)" 


echo "antype à'(sig)à' as à'STR 2';" 

echo "resource à'(sig)à' (8) 9(" 

echo '"Skeleton Application - Version 1.0"' 
echo "9);" 


8 goFREF Macro 

set exit 0 850 ‘cancel’ buttons not fatal 
" (MPW)nacros:getResAttrs" FREF 

set ty "'request ‘File Type (4 chars)2'"" 

set in ‘request ‘Icon ID'* 

set tex "‘request ‘Title?’ *" 

set ty "d'(ty}o'" 

echo " (ty), (in), д"({ех)д"дпд);" 


# Window Resource Macro 
set exit 0 850 ‘cancel’ buttons not fatal 


" (MPW)necros:getResAttrs" WIND 


set br "request 'BoundsRect? (t,l,b,r2'"" 
set ty "request -d d 'Box: 


‹О›ос | ‹В›ох | ‹Р›1аіп | «A» 1t | ‹№ одго | «2 оом | «P^ nd' ` 


conf irm 'Visible?' 
if (status) == 
set vis "visible" 
else 
set vis "invisible" 
end 
confirm 'GoAway?' 
if (status) == 0 
set go "goAway" 
else 
set go "побоАмаџ" 
end 
set ref ‘request -d 0 ‘Reference Constant?’ ` 
set tex "'request -d Untitled 'Title?'"" 


"determine window type 
if (ty) =~ /tDd1s/ 
set wtyp "documentProc" 


Ise 
if (ty) =~ /[Bb12/ 
set wtyp "dBoxProc" 
else 
if (ty) =~ /IPp1s/ 
set wtyp "plainDBox" 


18е 
if (ty) =~ /[Aal#/ 
set wtyp "altDBoxProc" 
else 
if (ty) =~ /tNn]2/ 
set wtyp "noGrowDocProc" 
else 
if (ty) =“ /1221ғ/ 
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set wtyp "zoomDocProc" 


else 
if (ty) =" /[Rr]s/ 
set wtyp "rDocProc" 
else 
set wtyp "unKnown" 
end 
end 
end 
end 
end 


end 
end 


#111 out rez entry 
echo " д((Ьг)д)," 

echo " (wtyp), 
echo " (vis)," 
echo " (go)," 

echo " (ref),8t0/* refcon *д/" 
echo " à"(tex)à"" 


echo "9);" 
# Create Menu Resource 
set exit 0 850 ‘cancel’ buttons not fatal 


" (MPW)macros:getResAttrs" MENU 
"set id "'request ‘Menu ID?'"" 


set mdef "'request -d textMenuProc 'ID of MenuDef proc?'"" 


oe 


set flags 
set mEnable "'request -d enabled ‘Enable Menu?’ *" 


request -d allEnabled ‘Enable flags (8 hex no.2'"" 


set title "'request ‘Title? (type “apple” for that menu)'*" 


"out overall info together here 
copy 0:4/àn/ "(scr)" "get saved ID 
paste 8 "(active)" 
echo ",0tàtàtao/* ID *д/" 
echo "(mdef),0t3/* menu def proc ID *9/" 
echo "(flags}, dtdtd/* item flags *9/" 
echo " (тЕлаб1е), dtdtdtd/* menu enable %2/" 
if (title) =" /[Aalpple/ 

echo "(title)," 


else 

echo "à"(title)o"," 
end 
echo -n "д1д( " 


8put together menu items 
set ict Ø "item count 


loop 
set ititle "'request 'Iten?'"" 
break if C(stetus) != Ø) OR C"(ititle)" ss "") 


set icon "noIcon" 

set key "noKey" 

set char "поМагк" 

set style "plain" 

confirm "Skip item attributes?" 
if (status) != B%wants attibutes 


begin 
set icon "'request -d noIcon ‘Icon No? C1-based; I will 
adust)'*" 
if (icon) != "noIcon" 
set icon ‘evaluate (icon) + 256" 
end 
set key "'request -d noKey ‘Key equivalent?’ *" 


confirm "Check?" 
if (status) == 0 
set char check 
else 
set char "noMark" 
end 

conf irm "Bold?" 
if (stetus) == 
set style bold 
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else 
set style "plain" 
end 
end 
end | 
if (ict) != Ø ; echo -n "dt " ; end?! alignment 
echo "à"(ititle)o"," 
echo -n "dt (icon)," 


if (key) != "noKey" 
echo -n "à" (key)à"," 
else 
echo -n "(key), " 
end 


*don't quote noKey 


echo "(char), (style) ; " 
set ict ‘evaluate (ict) + 1° 
end 


cut \;\ "(active)" #по ; after last entry 
echo "дпдід) dnd); " 


8 This interactively builds a 'DLOG' rez definition 
8 Frank Alviani - Tuesday, December 9, 1986 9:40:06 AM 


set exit 0 $so ‘cancel’ buttons not fatal 
echo "d/* ‘request 'Purpose:'" *9/" 
" (MPW)macros:getResAttrs" DLOG 


set br "'request 'BoundsRect? (t,l,b,r2'"" 
set ty ‘request -d d ‘Box: 
«D»oc| «B»ox| <P> 1аіп | <А› 141 «№ одго | «Z»oom| «P nd' ^ 
conf irm 'Visible?' 
if (status) == 
set vis "visible" 
else 
set vis "invisible" 
end 
confirm 'GoAway?' 
if (status) == 0 
set go "доАмаџу" 
else 
set go "noGoAway" 
end 
set ref "request -d 0 ‘Reference Constant?'" 
set tt] "'request -d Untitled 'Title?'"" 


"determine window type 
if (ty) =~ /І0діғ/ 
set wtyp "documentProc" 
else 
if (ty) =“ /[Bb]s/ 
set wtyp "dBoxProc" 
else 
if (ty) =" /ЇРр]#/ 
set wtyp "pleinDBox" 
else 
if (ty) =" /[Aal#/ 
set wtyp "altDBoxProc" 
else 
if (ty) =~ /INn12/ 
set wtyp "noGrowDocProc" 
else 
if (ty) =" /1721#/ 
set wtyp "zoomProc" 
else 
if (ty) =" /IRr]2/ 
set wtyp "rDocProc" 
else 
set wtyp "unKnown" 
end 
end 
end 
end 
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end 
end 
end 


8fill out rez entry 
echo " д((Ьг)}д)," 


echo " (ref),8t0/* refcon *д/" 

copy 0:4/ón/ "(scr)" get saved ID 
paste 8 "(active)" 

echo ",dtd/* DITL ID" *g/" 

echo " ào"(tt1)o"" 

echo "9);" 


н This interactively builds а 'CNTL' rez definition 
8 Frank Alviani - Monday, December 8, 1986 1:33:54 PM 


set exit 0 850 ‘cancel’ buttons not fatal 
echo "90/* "request 'Purpose:'^ *9/" 
" (MPW)nacros:getResAttrs" CNTL 
set p ‘request ‘Type: «B»tn|«Oheckbox|«R»adio| «S?ro11 
(Gr «Poont2'" 
set rr "'request 'BoundRect? (t,l,b,r2'"" 
set val ‘request -d 0 'Value?'^ 
set min ‘request -d Ø ‘Minimum?’ ` 
set max ‘request -d 0 ‘Maximum?’ ` 
confirm ‘Visible?’ 
if (status) == 0 
set vis "visible" 
else 
set vis "invisible" 
end 
set ref "request -d 0 'Reference Constent?'" 
set ttl ‘request -d x 'Title?'^ 


Sdetermine type 
if (p) =" /ІВБІР/ 
set ctyp "pushButProc" 


else 
if (p) =" /tCc]9/ 
set ctyp "checkBoxProc" 
else 
if (p) =“ /IRr19/ 
set ctyp "radioButProc" 
else 
if (p) =~ /ISs]s/ 
set ctyp "scrollBerProc" 
end 
end 
end 
end 


echo " д((гг)д)," 
echo " (vel),0t0/* value *à/" 
echo " (vis)," 
echo " (max),0t0/* max *д/" 
echo " (тіп), dtd/* min *д/" 
echo -n " (ctyp)" 
if (p) =" /stFf9/ 

echo "UseWFont, dtd/* type *д/" 
else 

echo ",dtd/* type %0/" 
end 
echo " {ref}, dtd/* refcon %2/" 
echo " д"({441)д"" 
echo "д);" 


Additional resource macros and make utilities for 
Pascal and C are available on the source code disk 


for this issue. 27 ) 
ёз?» 
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Connections 
AppleTalk: Fundamentals 


Connections is a new industry newsletter in the MacInTouch 
style that covers issues related to networking on the Mac. 
Connections and MacTutor have agreed to promote each 
other as "sister" publications and we will be re-printing 
articles from Connections in MacTutor from time to time. This 
article is re-printed from the first issue. Connections is edited 
and published by Dave Kosiur. Bob Denny of Alisa Systems 
serves on it's advisory board, as he does for MacTutor. 
Subscriptions are $60 per year for the bimonthly publication, 
available from Connections, PO Box 5894, Fullerton, CA 
92635. This is a valuable source of network specific informa- 


AppleTalk is Apple's design of a simple, inexpensive and 
flexible network for connecting computers, peripheral devices, 
and servers. AppleTalk's flexibility allows it to be used to 
connect peripherals such as the LaserWriter, or act as a stand- 
alone local-area network for up to 32 nodes, or form portions of 
a larger network by using bridges and gateway devices. 

Whatis AppleTalk? Ata purely physical level, AppleTalk 
is a network with a bus topology that uses a trunk cable between 
connection modules. Interfacing with the network is handled by 
the Serial Communications Control chip found in every Mac. 
Any device (computer, peripheral, etc.) attaches to a connection 
box via a short cable (called a drop cable), as shown in figure 1. 
This type of network is known as a multidrop line or a multipoint 
link. AppleTalk is capable of supporting up to 32 nodes (devices) 
per network and can transmit data at a rate of 230,400 bits per 
second. Nodes can be separated by a maximum cable length of 
1000 feet. 

AppleTalk, as specified by Apple, is wired using relatively 
inexpensive shielded, twisted-pair cable and Apple's connection 
boxes. One box is required per device; in the case of the Mac, the 
box plugs into the serial printer port in the back of the Mac using 
an attached drop cable. A trunk cable segment from one node on 
the network plugs into one port on the connection box, and 
another cable segment leading to the next node in the network 
plugs into the other port on the box. 

One of the advantages of AppleTalk relates to the design of 
these connection boxes. The boxes are designed so that the 
continuity of the trunk cable and the network is maintained even 
if a device is disconnected from the network by unplugging it 
from the connection box. (Unplugging the trunk from the 
connection box does disrupt the integrity of the network, how- 
ever.) The physical layout of an AppleTalk network can there- 
fore be designed by locating the connection boxes where desired 
without worrying if a device will be initially connected to each 
one of the boxes. Additional devices can be added to the network 
at any time simply by plugging them into the boxes. 
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Fig. 1 The Physical Connection 


There are alternatives to using Apple's connection boxes. 
Farallon Computing markets their PhoneNET system, which 
fully supports the AppleTalk protocols. In the case of Phone- 
NET, the physical transmission medium is ordinary telephone 
wire, allowing the user to use the in-house telephone wiring for 
his network. PhoneNET uses the two of the unused wires found 
in a normal telephone installation, supporting both a telephone 
anda Mac connected to the same telephone wall box. In addition, 
PhoneNET links are capable of supporting 3000-foot distances 
between nodes. Farallon has a series of devices (repeaters, Star 
Controller) for extending the network. 

With the recent announcement of DuPont's system for 
AppleTalk, users can also use fiber optic connections for an 
AppleTalk network. А concentrator is also available for con- 
structing star networks. Two advantages of the fiber optics 
system are its immunity to EMI-RFI interference and improved 
data security; nodes may be a maximum of 4900 feet apart. 

AppleTalk Protocols and the OSI Model 


The Physical Layer has the responsibility of bit encoding/ 
decoding, synchronization, signal transmission/ reception and 
carrier sensing. As mentioned previously, the Serial Communi- 
cations Control chip in the Mac takes care of the AppleTalk port, 
which happens to be the printer port on current Macs. As long as 
connection modules conform to the signal descriptions of the 
Physical Layer, any transmission medium can be used for the 
actual network. 

The AppleTalk Link Access Protocol (ALAP) must be 
common to all systems on the network bus and handles the node- 
to-node delivery of data between devices connected to a single 
AppleTalk network. ALAP determines when the bus is free, 
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encapsulates the data in frames, sends 
its data, and recognizes when data 
should be received. ALAP is also 
responsible for assigning node num- 
bers to each station on a network. The 
ALAP software assigns a random 
node number when the Mac is booted 
and keeps that number as long as it 
does not conflict with a previously 
assigned node number (if it does con- 


Presentation 


Summary of AppleTalk Protocols 


AppleTalk 
Filing 
Protocol (AFP) 


flict, ALAP tries again). 

The Link Access Protocol uses a AppleTalk Zone AppleTalk Printer 
method called CSMA/CA, or carrier- DataStream Information Session Access 
sense multiple access with collision session Бай е кекс EIF) Protocot (ASI) Protocol (РАР) 
avoidance, for access control. Carrier 
sense means that a sending node first 
listens to the network to hear апу — "'"" "mme Fe 
other node is using the bus and defers EUN n " 
to the ongoing transmission. Colli- парод | esee Ta ONE E L-—— ТЕЕ 
sion avoidance means that the proto- Protocol (RTMP) Protocol (ATP) Protocol (NBP) 
col attempts to minimize collisions 
between transmitted data packets. In 
AppleTalk CSMA/CA, all transmit- шаны аты 
ters wait until the bus is idle for а 
of added time before transmitting (or 
retransmitting after a collision). 

While the ALAP protocol pro- 
vides delivery of data over a single AppleTalk 
AppleTalk network, the Datagram Link Access 
Delivery Protocol (DDP) extends this Data Link Protocol (ALAP) 
mechanism to includea group of inter- 
connected AppleTalk networks, AAAI s Mess t A ARRA AN AAA NAA RA REAR 
known as an internet. An internet can 
be formed, for example, by using а Physical 


bridge between two, or more, Ap- 
pleTalk networks. 


AppleTalk's address header (a part of each data packet) is 
used for identification of a process on the network and consists 
of a socket number, node number, and network number. A 
Socket is a communication endpoint within a node on the 
network. Sockets belong to processes or functions that are 
implemented within software in the node. One Mac may have 
several AppleTalk connections open at one time, so the node 
number is not enough to identify a network address. In addition, 
node numbers are unique only within a single physical network, 
so DDP requires that each network be assigned a network 
number. The Datagram Delivery Protocol takes care of assign- 
ing Socket numbers, as well as node numbers and network 
numbers, to provide a unique identification for every process 
occurring on the AppleTalk network. 

As we move on to the Transport Layer, several protocols 
exist to add different types of functionality to the underlying 
services. The Routing Table Maintenance Protocol (RTMP) 
allows bridges and internet routers to dynamically discover 
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routes to the different AppleTalk networks in an internet. The 
routing tables pair network numbers with the local node number 
of the bridge through which the shortest path to that net exists. 

The AppleTalk Transaction Protocol, or ATP, is part of the 
Transport Layer and is responsible for controlling the transac- 
tions (flow of data) between requestor and responder sockets. 
This transaction-oriented protocol can be contrasted to other 
types of transport layers which support a two-way link between 
clientsthat can actas though they hadan error-free hardwired link 
between them. 

The basic function of the Name Binding Protocol (NBP) is 
the translation ofa character string name into the internet address 
of the corresponding client. A key feature of the network is that 
mostobjects are accessible by name rather than by address (better 
for the user). NBP also introduces the concept of a zone, which 
is an arbitrary subset of networks in an internet where each 
network is in one and only one zone. The concept of zones is 
provided to assist the establishment of departmental or other user- 
understandable grouping of the entities of the internet. Ap- 
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pleTalk names consist of three fields: the object name (e.g., 
Dave), the type name (e.g., printer), and the zone name (e.g., 
Bldg. 1). 

The Echo Protocol (EP) is a simple protocol that allows any 
node to send data to any other node on an AppleTalk internet and 
receive an echoed copy of that data in return. The Echo Protocol 
is mainly meant for network maintenance functions. 

The specifications for the AppleTalk Data Stream Protocol 
(ADSP) have not yet been published (Inside AppleTalk, current 
version dated July 14, 1986). ADSP is designed to provide byte- 
stream data transmission in a full duplex mode between any two 
Sockets on an AppleTalk internet. The Zone Information Proto- 
col (ZIP) is used to maintain an internet-wide mapping of 
networks to zone names. Most of ZIP's services are transparent 
to the normal (non-bridge) node; the majority of ZIP is imple- 
mented in the bridges of an internet. ZIP is used by the Name 
Binding Protocol to determine which networks belong to a given 
zone. 

Inthe Session Layer, the AppleTalk Session Protocol (ASP) 
is a general protocol designed to interact with ATP to provide for 
establishing, maintaining and closing sessions. Central to ASP 
is the concept of a session; two network entities, one in a 


Networking Issues 


File Servers versus Disk Servers 


Your kindly editor, Dave Smith, has invited us to clear up 
some common misperceptions about TOPS, and generally dispel 
the fog of confusion that surrounds the whole area of networked 
file systems. А widely distributed Mac magazine recently ran a 
short piece on the difference between file servers and disk servers 
that was almost completely wrong, and at trade shows one often 
hears sales people giving out incorrect information. This article 
should help people to navigate through the dimly-lit coral reefs 
of networking. 

There are three main approaches to sharing files over a 
network: file transfer, disk service, and file service. (There is also 
disk transfer, known to initiates as "the Frisbee method".) 

The most venerable approach is file transfer. Most pro- 
grammers have used file transfer over phone lines; it's much the 
same over a network. Instead of dialing a phone number, one 
types in or selects a machine name, but the basic sequence of 
operations is the same. The user asks to send or receive a file to 
or from a remote system. Cooperating software on both ma- 
chines breaks the file up into small packets of data and reliably 
transfers and acknowledges the packets over the serial line or 
network. Each packet is sent with a "checksum" or "cyclic 
redundancy check" value derived by performing a sequence of 
arithmetic operations on the bytes in the packet. If the receiving 
machine finds that a packet doesn't match its checksum or CRC, 
it asks for the packet to be sent again. In this way, the entire file 
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workstations and the other in a server, can set up an ASP session 
between themselves (identified by a unique sessions identifier). 
ASP is an asymetric protocol in that the workstation initiates the 
session connection and issues sequences of commands, to which 
the server responds; the server may not send commands to the 
workstation. 

The specifications for the AppleTalk Filing Protocol (AFP) 
have not been generally publicized. However, AFP has been 
finalized with the introduction of the AppleShare file server 
software from Apple, which uses AFP. AFP is a presentation 
layer protocol designed to control access to remote file systems. 

At this time, third-party products are available for connect- 
ing Macintoshes and IBM PCs to AppleTalk, as well as using 
gateways for access to EtherNet as a backbone network to larger 
computers. Future articles in Connections will deal with these 
products and the diversity of products (file servers, spoolers, etc.) 
that can take advantage of such connections. For additional 
information, see MacTutor, Vol. 1, Numbers 10 and 11 for 
articles by Bob Denny & Alan Wootton. 
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is sent with guaranteed correctness. On serial lines, the protocol 
is likely to be Kermit or XMODEM; on a network, it is likely to 
be FTP (File Transfer Protocol). 

An open secret of networking is that there is no such thing 
as a perfect guarantee of correctness. It is possible for a packet 
to be completely garbaged by line noise, but to coincidentally fall 
together into an acceptable packet with a valid checksum. It is 
also possible, as Gamow pointed out, for all the molecules of air 
in aroom to randomly wind up in the same corner of the room and 
leave any people in the room gasping in a vacuum. It isn't 
particularly likely, and neither is a network or line error that 
yields a valid checksum or CRC value. 

File transfer is adequate for many applications, particularly 
keeping libraries of software or literature which people want to 
download to their machines. However, there are a number of file 
sharing applications which require a more dynamic approach. 
For instance, if you have a distributed database, you don't want 
to have to download it to your machine, make changes, and then 
upload it back to the original machine. In a multiple-engineer 
programming product, it might be desirable to keep the sources 
on a central machine and have everyone work from the same 
copies, while actually using their own microcomputers. Some- 
times you have only one hard disk but three people need to have 
а few megabytes each at the same time. And so forth. For these 
kinds of applications, disk service or file service is more suitable. 
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Disk service and file service look similar to a human user, 
butthe implementations are different in significant ways. In both 
cases, though, the idea is to make disk storage that is connected 
to another machine seem to be directly connected to your ma- 
chine. On the Mac, that means (from a user's perspective) that a 
remote disk volume appears with a disk icon in the Finder, and 
can also be seen inside the Standard File Package, so that the files 
on the remote disk can be used just like local files. The term 
"transparency" is usually used to refer to this kind of file access; 
the fact that the file actually resides on another system is trans- 
parent (invisible) to software. In other words, transparency of 
disk or file service means that old programs still work, without 
having to put out new versions. 

You can see that file transfer is actually a functional subset 
of disk service or file service. Network file transfer can be done 
in the Finder on the Mac using TOPS or MacServe, without 
requiring a special transfer utility; all you have to do is drag the 
remote file to a local (or even another remote) volume or folder. 

In just about every operating system on the planet, there are 
two levels of file access. The programmer uses high-level file 
operations, like open, read, write, close, and so forth. High-level 
file operations are translated by the operating system into low- 
level disk operations involving physical disk block reads and 
writes. Low-level operations are usually structured as calls to 
any of several lookalike disk drivers, pieces of software in the OS 
that deal with the details of communicating with the disk control- 
ler. An operating system is associated with a particular disk 
format, which is the same from disk to disk. That is, regardless 
of whether you have a DataFrame or an HD20 connected to your 
Mac Plus, the first two blocks on the disk contain system startup 
information, the third volume information, and so forth, even 
though two different disk drivers are used to talk to the disks, and 
the disks represent their blocks differently at the physical level. 

Disk service intercepts file operations at the level of the disk 
driver. File service, however, intercepts file operations in the 
high level operations. This leads to some important differences 
in the power and performance of the two approaches. 

In disk service, a disk (or possibly a simulated disk) on a 
remote machine is accessed by the operating system just like a 
local disk; physical disk block reads and writes go directly over 
the network. Disk service uses a disk driver that goes to the 
network instead of to a local file device. You could say that the 
network is being used like a long SCSI cable. Disk service is very 
simple to implement; a friend once claimed that he could write a 
complete disk server in under two hours. 

Clearly, disk service is bound by disk formats, and so it does 
not work very well, if at all, between different operating systems. 
A Mac and a PC want to see very different things on their disks. 
It is possible, though difficult and expensive, to let each under- 
stand the other's format; for instance, an external file system 
could be written on the Mac to understand PC-format disks. 
However, there is a combinatorial explosion associated with 
adding more formats. Each new system's format has to be 
implemented on each already supported system, requiring lots of 
coding effort, and lots of code space overhead on each machine. 
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Disk service does not easily permit file sharing between 
users. Disk service uses an existing, unmodified or only very 
slightly modified, disk format, the format that came with the 
operating system. Disk formats do not typically allow easy 
synchronization of multiple users, because they are intended to 
be used only by a single local machine. This means that only one 
person can mount a network disk at one time, unless elaborate 
operating system interceptions and synchronization protocols 
are developed. If such interceptions and protocols are done, then 
disk service is no longer simpler than file service; and this 
simplicity was really its only benefit. 

One approach to inter-operating-system disk service is to 
partition a server's disk, and format each partition to the dictates 
of a different OS. To share files between operating systems, a 
special utility is used to copy across partitions. This is the 
approach used by 3-Com. This allows dynamic file sharing 
between machines using the same operating system (some- 
times), but between operating systems it is really just file transfer. 
Using simulated disks has some of the same problems as parti- 
tioning; for instance, you could allocate a one megabyte file on 
a VMS system and use disk service software to make a Mac think 
this VMS file is really a block-structured Mac disk, but people on 
VMS are not going to be able to get any useful information с out 
of the file without using special copying utilities. 

In file service, high-level file system operations like open, 
read, write, lock, and so forth go over the network instead of disk 
block requests. In many file service protocols (e.g., TOPS, NFS, 
and CMU's VICE), a remote function call protocol is used for 
support: this allows one machine to make function calls that are 
executed on another machine. File service is usually very hard 
to implement well; TOPS took about two years, and VICE took 
even longer to become a usable system. 

However, once file service is done, there are some very 
tangible benefits over disk service. The most tangible, to a naive 
end user, is that remote disks can be shared; more than one person 
can have access to the same directories and volumes at one time. 
No special synchronization protocol is needed. 

Another very tangible benefit is an inter-operating-system 
capability. Most operating systems have similar high-level file 
operations, like open, read, seek, and so forth. There are 
differences, but they can almostalways be bridged without losing 
compatibility. TOPS is a standard for file system operations 
regardless of operating system, and was simultaneously devel- 
oped on two operating systems: that's how we were able to get the 
PC and the Mac to communicate, and why our UNIX and 
forthcoming OS implementations are proceeding smoothly. 
Some other file service protocols are less OS independent; for 
instance, VICE is very specific to 4.2bsd UNIX, and a new 
protocol, SNAP, had to be added to allow VICE machines to 
share files with microcomputers. 

Another benefit is that considerably more clever and pow- 
erful things can be done in file service. VICE uses a whole-file 
local caching scheme that speeds up file access tremedously for 
workstations that have their own disks. A file service protocol 
can be extended easily to cope with the demands of new operating 
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systems, without encountering the combinatorial explosion of 
disk service. Disk servers, because of the lack of file sharing, do 
not usually allow a machine to serve as both client and server, or 
to function as one node in a homogeneous network namespace; 
these things can be added to file service relatively easily. 

File servers are often faster than disk servers. TOPS, a file 
server, is faster than MacServe, a disk server, according to 
InfoWorld (11/86) and MacWorld (10/86). This might seem 
puzzling, since disk service is simpler than file service. We aren't 
entirely sure, but we think that it is the result of disk service's need 
to pass directory and map blocks over the network to do direc- 
tory, seek, and grow operations. In file service, this is all done 
locally on the server machine, accomplishing in a single network 
operation what takes two or more with disk service. Of course, 
local operations are faster than network operations, just as eating 
everything at the table is faster than walking to the kitchen to 
fetch each mouthful. Believe me, I have tried this many times. 
So contrary to first impressions, a file server can often be 
expected to perform better than a disk server. 

Some brief design notes might be helpful. TOPS is a name 
used for both a network protocol and the TOPS product which 
implements the protocol. The TOPS protocol is built on a lower- 
level protocol called RFP, for Remote Function Protocol. Using 
RFP, it is possible to make function calls that will be executed on 
another system. КЕР itself is built on top of the Appletalk 
Transaction Protocol (ATP), and will soon be ported to run on the 
Internet Transmission Control Protocol (TCP) as well. RFP is an 
asymmetrical protocol; it has a client end, which makes remote 
calls and receives their values, and a server end, which receives 
remote calls, executes them locally, and returns the result to the 
client that initiated the call. 

The TOPS protocol is a set of function definitions that are 
passed over the network using RFP. These include functions to 
open files, read and write buffers, lock files and byte ranges, get 
information on files and directories, and so forth. When some 
software on the Mac makes a file system call that has to do with 
aremote file, this system call is intercepted and translated into a 
TOPS call. RFP's client end is then used to make this TOPS call 
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remotely on the system where the file is actually stored. The RFP 
server end on the machine containing the file executes the TOPS 
calllocally, which meanscalling the local file system, and returns 
the result to the client. Because everything goes through TOPS, 
the two machines may have completely different operating 
systems. All that is needed is for the TOPS client software to 
translate local file system operations into TOPS operations, and 
for the TOPS server to translate TOPS operations into local file 
system operations. 

The Apple Filing Protocol (AFP) and Sun's Network File 
System (NFS) use somewhat similar designs. With AFP, a 
protocol called ASP (Apple Session Protocol) is used for remote 
functioncalling. Actually, ASP does less than RFP, since it does 
not itself interpret the data in the packets, deferring this to a sort 
of implied remote function call layer in AFP itself. (Pay atten- 
tion; this will be on the test.) ASP sits on top of ATP; like AFP, 
it was co-developed by Centram and Apple. NFS uses a protocol 
called RPC (Remote Procedure Call), which uses a sub-protocol 
known as XDR (External Data Reference) to define its data 
formats. RPC sits on top of the Internet User Datagram Protocol 
(UDP). 

There were some comments on TOPS from "MacoWaco" in 
the January 1987 issue of MacTutor which were not quite 
accurate regarding use of Apple's "File Structure". I don't know 
what he means by "Apple's File structure". The most likely 
interpretation seems to be the Apple Filing Protocol, AFP for 
short. This is an Apple protocol for network file service. The 
design of AFP is similar to the design of the TOPS protocol. AFP 
is still being refined within Apple; when it is finalized later this 
year, TOPS will become fully compatible with it. MacServe, 
however, cannot be compatible with AFP. Its disk service 
approach is fundamentally incompatible with the file service 
approach employed by both TOPS and AFP. Another possible 
interpretation of "Apple's File structure" pertains to disk format. 
TOPS uses disks as they are, with no modifications needed, while 
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Sue Goodin is a Technical Communications Engineer for Apple 
Computer. Dave Wilson is President of Personal Concepts, a 
consulting firm specializing in training courses for the Macin- 
tosh. He is currently teaching Apple's MacApp programming 
course. In this article, Sue and Dave review the new Apple 
product offerings and the new ROM calls behind the new fea- 
tures. 


Figure 1 summarizes the latest results of Apple's increased 
R & D spending, and certainly indicates that the folks in Cu- 
pertino have been busy. In this article, we want to review and 
preview information about some of these new products, empha- 
sizing details of interest to programmers. Apple's new computers 
represent new market opportunities, and new programming 
challenges, so we should discuss both areas. 

The evolutionary Macintosh SE should be an even more 
popular machine than the successful Macintosh Plus, since it 
offers somewhat better performance and an expansion slot for 
adding a peripheral board. Its 256K ROM offers some new 
features, as discussed below, but is primarily focused at retaining 
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compatibility with present Macintosh software, so there are no 
earthshaking changes for programmers to worry about. 

The revolutionary Macintosh II, on the other hand, is a very 
well-designed and powerful machine that will open up com- 
pletely new markets and opportunities for us all. The only catch 
is that the Macintosh II is even more sophisticated and compli- 
cated than earlier Macintoshes, so we have a lot more to learn 
before our software can really shine. Will our present programs 
work on the II? They should. Apple believes that more than 2/ 
3 of the present software will run unchanged, and almost all 
software that follows the compatibility guidelines should work 
fine. 


The Macintosh SE 


The Macintosh SE (stands for System Expansion) still has 
an 8 MHz 68000, but has new 256K ROMs, and one expansion 
slot. It has the standard built-in 9-inch monochrome monitor, but 
you can, of course, add other monitors using the expansion port. 
You can put up to 4 MB of RAM in an SE. 

A tricky point is that both the Macintosh SE and the 
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Macintosh II have 256K ROMS, but they are not the same. The 
Macintosh II's ROM has Color QuickDraw and other goodies 
that are not in the SE. The SE was designed for software 
compatibility, and over 90% of existing applications should run 
оп it. The Macintosh II is less compatible, with over 60% of the 
software running unchanged. Macintosh II ROMs are complete, 
andits system software is in the final testing stages, while the SEs 
are in the stores now. 

The SE provides somewhat improved performance over the 
Macintosh Plus, as we shall see. Apple still intends to sell both 
the Macintosh Plus and the 512K Enhanced, because they pro- 
vide a lower-priced entry point in the product line. 


The Macintosh Il 

Overview 

The Macintosh II offers a 68020 microprocessor with a 
68881 floating point coprocessor, 1M or more of RAM, and 6 
NuBus expansion slots. The Macintosh II supports color and 
gray-scale display, and has four-voice sound capability. The 
Macintosh II includes: 


• 68020 microprocessor, clocked at 16 MHz 

• 68881 floating point coprocessor (always there - not ап 

option) 

1M RAM (expandable to 2, 5, or 8M on the logic board) 

256K ROM 

6 NuBus slots 

general memory management unit (or optional 68851 

PMMU) 

e Two Apple Desktop Bus (ADB) ports for the mouse, key- 
board, tablets, etc. 

e One or two internal 800K floppy drives 

е Room for a 20, 40, or 80M internal SCSI hard disk 


The Motorola 68020 microprocessor has a 32-bit data bus, 
which can speed up Macintosh Plus software by a factor of 4. 
Other properties of the 68020 add to that speed advantage, and 
with the inclusion of the 68881 floating-point coprocessor, 
certain types of Macintosh code may now run as much as 200 
times faster on the Macintosh II than on existing members of the 
Macintosh family. 

The ROM in the Macintosh II has been completely rewrit- 
ten, and now includes Color Quickdraw, which supports the 
definition of as many as 2% colors (about 200 trillion). The 
Macintosh II Video Card with its Expansion Kit can display 256 
colors (or shades of gray) on the screen at once. 

The six NuBus slots provide a flexible means of expanding 
the architecture for such products as processor cards, video 
output, non-Apple Desktop Bus input devices, storage devices, 
and network cards. 

NuBus, Texas Instruments’ synchronous bus definition, 
allows any device to become master of the system. Therefore, 
80286 cards, EtherNet cards, and other intelligent interfaces 
may, at times, gain control of the CPU. With this architecture, the 
Macintosh II could run MS-DOS software, act as a smart termi- 
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nal, or drive a variety of output devices. Apple's NuBus implem- 
entation includes interrupt lines from each of the slots, and has 
changed the size of the interface card toconform to the Macintosh 
II case size. 

The addition of 4-voice sound is also supported by the 
Macintosh II hardware. The firmware now contains synthesizers 
for MIDI, note, wave table, and sampled sound production. 

Hardware 

Although a number of the external ports on the Macintosh 
II are similar to those on previous Apple equipment, the logic 
board of this computer is significantly different than other 
members of the Macintosh family. 

Memory management chores are handled by a general 
memory management unit, which allows the 68020 to devote its 
processing time to other tasks. A paged memory management 
unit (PMMU), the Motorola 68851, is available to support paged 
virtual memory management, and is required to run Apple A/UX, 
Apple's version of the UNIX operating system. 

Eight SIMM sockets, organized into two groups, provide a 
starting configuration of 1M memory. Apple will offer RAM 
upgrades to increase available memory on the Macintosh II to 
8M. As SIMM technology advances, the Macintosh II will be 
able to take advantage of up to 128M RAM on the logic board. 

The 256K Macintosh II ROM has been written to support all 
of the previously mentioned devices and features. The ROM also 
includes all packages available on the Macintosh Plus. The 
following features are among those that have been added to the 
ROM: 


е Color Quickdraw, and color support in other Manag- 
ers 

е Apple Desktop Bus support 

е More fonts - Monaco 9, Chicago 12, Geneva 9 
and 12 

e Slot Manager to handle NuBus card communication 

e 4 Voice Sound Manager 

• SCSI Driver 


The Macintosh II has two lithium batteries, with a lifetime 
rated at 7 years, soldered on the logic board. These replace the 
removable dry cell battery found on earlier Macintosh comput- 
ers. If your program crashes and writes garbage into Parameter 
RAM, you may have up to seven years of bad luck, so be sure to 
write perfect programs! Actually, Macintosh II users may con- 
tinue to use ParmBlaster -type programs to erase parameter 
RAM, should it become irretrievably corrupted. 

Six Macintosh II slots follow Texas Instruments' NuBus 
standard, with Apple modifications. The NuBus definition al- 
lows any NuBus device (of which the 68020 is one) to become the 
"system master". With its open architecture, the Macintosh II will 
encourage developers to sell processor cards, graphic interfaces, 
memory devices, and drive interface cards. 


One of the NuBus slots will normally be used by a video 
card, since the Macintosh II does not contain video signals on the 
logic board. Apple has a Macintosh II Video Card available for 
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use with the Apple High Resolution Monochrome Monitor and 
the AppleColor High Resolution RGB Monitor. The card's 
factory-installed memory can allocate up to 4 bits per pixel, for 
a maximum display of 16 colors or shades of gray. With the 
optional 8-Bit Expansion Kit, as many as 256 colors and gray- 
scales may be shown. 

Macintosh II Video Card 

The Macintosh II graphics plug-in video card provides color 
capability for simultaneous display of up to 256 colors on the 
Apple High Resolution Color Monitor. This capability is further 
enhanced by its three 8 bit digital to analog converters (RGB) 
providing more than 16 million possible colors to choose from. 
Color modes range from one bit per pixel (2 colors) to an optional 
eight bits per pixel (256 colors). 

On the same card, using the Macintosh II control panel desk 
accessory options, you may select true grey scaling. With the 
Macintosh II Video Card , the grey shading is intensified or 
diminished by hue and brightness values. The user no longer has 
to rely on the spaced dot patterns of previous grey schemes. 
When grey scaling is selected from the control panel, each of the 
presently available colors is translated into a shade of grey. 

PMMU 

A Motorola MC68851 co-processor is used by the Macin- 
tosh II to implement paged memory management. This chip 
replaces the standard memory management chip in the Macin- 
tosh II, and is used by systems programmers to implement 
advanced and multi-user operating systems, like Apple's A/UX. 
While the standard MMU simply offers two modes of translation 
(а 32 to 24 bit mode for software compatibility with programs for 
older Macintoshes, and a straight-through 32 bit mode), the 
PMMU offers such features as: 


e 32 bit logical to physical address translation with 4-bit 
function codes. 
e memory protection by access level and access type. 
e hardware maintenance of address translation, and address 
translation cache (ATC). 
e 16 extensions to the 68000 family that provide control for: 
- loading and storing of MMU registers. 
- testing access rights, and conditionals based on the 
results of this test. 
- MMU control functions. 


Expansion through NuBus 

The 68020 communicates through the memory manage- 
ment unit with each of the six synchronous NuBus slots through 
a full 32-bit address/data transfer between each slot and the 
68020. Each slot is identified to the microprocessor by 4 ID lines, 
which the bus master uses to determine the source of the commu- 
nication. Power, timing, and acknowledge lines are also imple- 
mented. Apple has changed Texas Instruments' NuBus definition 
by adding an interrupt line from each slot, so that each card can 
generate an interrupt to the on-board logic. 

The 32-bit address space (equating to 4G bytes) available 
for all NuBus slots is partitioned to provide space for each slot. 
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First, the top 256M of address space is divided into 16 "slots". 
This allows each physical slot to "own" 16M, which is referred 
to as its Slot Space. Each NuBus slot is also allocated 256M 
(although it may request more!) of "SuperSlot Space" from the 
portion of memory remaining in the 4G of address space. 

Each NuBus card should contain a configuration ROM 
mapped to the top of its Slot Space. This ROM provides informa- 
tion so the Macintosh II operating system can identify the card at 
startup time. The Macintosh II looks at the ROM to determine the 
type of card, how it is to be accessed, and its slot resource data. 

Pre-defined NuBus card categories include display, net- 
work, terminal emulator, serial, parallel, intelligent bus, and 
human input devices. Each category is further defined by a type 
indicator. For example, the network category is subdivided into 
AppleTalk, EtherNet, TokenRing, etc. With this information, 
slot drivers can then locate any appropriate card by checking 
these bytes in configuration ROM on each card. 

NuBus cards may be designed to be "masters" of the bus, or 
as slavesonly. А master card must be able to initiate bus transfers 
of 8, 16, or 32 bits, and must be able to arbitrate requests for bus 
mastership. It may have the ability to lock the bus from access by 
other NuBus devices for a specified period of time. A slave card 
responds to requests, but can only send a "non-master request", 
and need not support the full 32-bit transfer. 

Keyboards 

Two new keyboards were announced that each hook up to 
the Apple Desktop Bus, along with the mouse. The larger one will 
look quite friendly to those of you who sell to the IBM world, with 
15 function keys that you can have your program interpret in any 
way that you wish. The keyboard has an output for other ADB 
devices, so the mouse can be connnected directly to the keyboard 
(on either side). 


The ROM 

New Managers in the ROM 

The Macintosh II ROM features have been greatly extended 
from those found in the Macintosh Plus. A number of new 
managers have been added to the ROM, and most existing 
managers have been modified to support the new hardware 
capabilities of the Macintosh II. 

The modifications most frequently introduced involve 
color support - QuickDraw, menus, dialog boxes, and TextEdit 
are among those items that have been extended with color 
features. The NuBus slots are also a prime candidate for causing 
additions and changes. The Macintosh II introduces a Slot 
Manager, an Operating System Utilities Manager, and the De- 
ferred Task Manager to support Apples NuBus implemen- 
tation. 

Other managers have been rewritten to remove previous 
limitations: the Macintosh II is an open machine, so the ROM 
designers have made every effort to permit developers the 
freedom to design products for the Macintosh II without being 
concerned with ROM limitations. 

We'll list information about some of the new managers, in 
roughly alphabetical order. In some cases we include descrip- 
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tions of new data structures and ROM calls, but you should 
remember that these are preliminary specs. A.P.D.A. should now 
be shipping a draft of Inside Macintosh Volume V to provide all 
the hairy details. 

Apple DeskTop Bus Manager 

The Apple Desktop Bus was introduced with the Apple 
IIGS last fall. Apple is now implementing the same technology 
on the Macintosh SE and Macintosh II. Apple Desktop Bus 
provides a low-cost, simple local bus network used by low speed 
input devices, such as keyboards and mice. The ADB can control 
as many as 16 devices on its network, each of which is identified 
to the ADB controller by a unique identifier. The CPU can issue 
commands to the network at large, or to a particular device on the 
bus. Four ADB commands are supported: 


ғ Reset Forces a hardware reset of ADB devices. 

e Flush [Initializes the addressed ADB device. 

е Talk Requests information from ADB device. 

e Listen Sends an instruction from the CPU to 
ADB device. 

Color Capabilities 


The Macintosh II supports both QuickDraw color, as imple- 
mented in Macintosh Plus ROMs, and a new Color QuickDraw, 
as defined in the sections below. 

"Classic" QuickDraw color was designed to conform to a 
planar model, where each of the bits used to describe a color turns 
a particular color plane on or off. QuickDraw used this technique 
to define eight standard colors, each with a unique bit pattern, to 
be used as the foreground or background color of a GrafPort, in 
RGB display, or in color printing. If you write programs using 
classic QuickDraw, they will run perfectly well in black and 
white on a Macintosh Plus or SE, but will appear in color on the 
Macintosh II. 

The new Color QuickDraw uses an absolute approach to 
determine color representation. А new data type, RGBColor, is 
defined to be a record containing three 16-bit integers, each of 
which represents an intensity value for one of the three additive 
primary colors red, green, and blue. 


TYPE 
RGBColor = RECORD 
red: INTEGER; (Red component) 
green: INTEGER; (Green component) 
blue: INTEGER; (Blue component) 
END; 


Under Color QuickDraw, the application need not be con- 
cerned with the type of output device. The application specifies 
a color in RGBColor format, but the Color Manager then uses 
information from the display device's driver to translate the 
RGBColor definition into the best available match on the output 
device. Some output devices may be limited to 8 or 16 colors; 
others use a lookup table to select from a wide range of possible 
display colors. In any event, the Color Manager handles these 
details independently of Color QuickDraw or the application. 
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On the Macintosh П, the user may choose the depth to which 
the screen image should be displayed, up to the limits of the video 
hardware, by using the Control Panel desk accessory. This 
permits the customer to choose a display that is consistent with 
the type of program. А word processing application may need 
only black and white, and a greater selection of colors (i.e., 
greater depth) would only slow down the application. On the 
other hand, drawing and charting applications benefit from the 
ability to use more colors, so the user might choose to use a 
greater pixel depth. 

Pixel depth must be a power of 2. A display of 4 bits per pixel 
permits each pixel to choose from among 16 colors, while 8 bits 
per pixel allows a selection of 256 colors. Normally, the device 
will implement these choices through a color lookup table 
controlled by the Color Manager. 

Color QuickDraw 

Color QuickDraw includes the same types of procedures 
and calls found in "old" QuickDraw, but it has expanded to 
support color on the Macintosh II in GrafPorts, pixel maps, icons, 
polygons, and cursors. 

A new data type, the CGrafPort, is analogous to a GrafPort, 
but it replaces pattern and map information with handles to a 
PixMap, pnPixPat, bkPixPat, and pnFillPat. The resulting free 
bytes have been used to add RGBColor records for the fore- 
ground and background of the port. 


CGrafPort = record 
integer; (Device ID font select) 


device 


por tPix : PixMapHandle (Port's pixel map) 

portVersion : integer; (Color QuickDrew ver. no.) 

cgRsrv 1 : longint; (Reserved) 

cgRsrv2 : longint; (Reserved) 

portRect : Rect; (Port Rectangle) 

visRgn : RgnHendle; (Visible region) 

clipRgn : RgnHendle; (Clip region) 

bkPixPat : PixPatHandle; (Background Pattern) 

rgbFgColor : RGBColor; (request foreground color) 

rgbBkColor : RGBColor; (request background color) 

pnLoc : Point; (Pen location) 

pnSize : Point; (Pen Size) 

pnMode : Integer; (Pen Trensfer Mode) 

pnPixPet : PixPatHandle (Pen pattern) 

pnFillPet : PixPatHandle (Fill pattern) 

pnVis : integer; (Pen Visibility) 

txFont : integer; (Font number for text) 

txFace : Style; (Text's character style) 

txMode : integer; (Text's trensfer mode) 

іхбіге : integer; (Font size for text) 

spExtra : fixed; (Extra Space) 

fgColor : longint; (Actual foreground color) 

bkColor : lengint; (Actual background color) 

colrBit : integer; (Plene being drewn) 

petStretch : integer; (Used internally) 

picSave : Handle; (Picture being saved) 

rgnSave : Handle; (Region being saved) 

polySave : Handle; (Polygon being saved) 

grefProcs : QOProcPtr; (Low-Level drew routines) 
END; 
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Here are some of the new calls for setting colors: 


PROCEDURE RGBForeColor (color: RGBColor); $AA 14; 
PROCEDURE RGBBackColor (color: RGBColor); $AA15; 
PROCEDURE SetCPixel Ch,v: INTEGER; сРіх: ColorSpec); %АА16; 


FUNCTION GetCPixel Ch,v: INTEGER): ColorSpec; $AA 17; 
PROCEDURE GetForeColor (VAR color: RGBColor); $AA 19; 
PROCEDURE GetBackColor CVAR color: RGBColor); $AA 1A; 


Color cursors and color icons are implemented through two 
new data structures, CCrsr and СЇсоп. Both structures remove 
size limitations from items by using handles to the actual data, 
rather than keeping data within the structure itself. Both cursors 
and icons access a pixmap, which allows the use of color at a 
depth of the user's choosing. 

All drawing by Color QuickDraw is done in a pixel map, 
which is analogous to the bitMap of old. New fields have been 
added to track the horizontal and vertical resolution in pixels per 
inch, the number of bits per pixel, and the handle to the pixel 
mapss color table. 


PixMep = record 


beseAddr : Ptr; (Pointer to pixel image) 


rowBytes : integer; COffset to next row) 

bounds : Rect; (Boundary Rectangle) 

pmVersion : integer; (Color QuickDraw version number) 

packType : integer; (Packing format) 

peckSize : longint; (Size of data in packed state) 

hRes : fixed; (Horizontal Resolution) 

vRes : fixed; (Vertical Resolution) 

pixelType : integer; (Format of pixel image) 

pixelSize : integer; (Physical bits per pixel) 

cmpCount  : integer; (Logical Components per pixel) 

cmpS ize : integer; (Logical bits per component) 

pleneBytes : longint; (Offset to next plane) 

pnTeble : CTebHendle; (Absolute colors for image) 

pmReserved : longint; (Reserved for future expansion) 
END; 


Here are two routines for handling PixMaps: 


PROCEDURE CopyPix CsrcPix,dstPix: PixMap; srcRect,dstRect: 
Rect; mode: INTEGER; maskRgn: RgnHandle); $ABEC; 

PROCEDURE CopyCMesk (srcPix: PixMap; maskBits: BitMap; dstPix: 
PixMap; srcRect,maskRect,dstRect: Rect); $A8 17; 


Color QuickDraw includes color patterns. It provides an 
undefined limit to the size of the pattern, and a variable pattern 
depth. Although Color QuickDraw is capable of translating the 
depth of a pattern to the current screen display depth, this can be 
a time-consuming process, and should be avoided. As always, 
color patterns provide a method of dithering, which increases the 
number of perceived colors shown on the screen by trading off 
resolution. 


Here are some of the new calls for drawing in color: 
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PROCEDURE FillCRect (г: Rect; pp: PixPatHandle); $AAgE; 
PROCEDURE FillCOval (г: Rect; pp: PixPatHandle); $AAQF; 
PROCEDURE FillCRoundRect (r:Rect; ovWd,ovHt: 

INTEGER; pp: PixPatHandle); $AA 10; 
PROCEDURE FillCArc (г: Rect; startAngle,arcAngle: 

INTEGER; pp: PixPatHandle); $AA11; 
PROCEDURE FillCRgn (гоп: RgnHendle; pp: PixPatHandle);$AA12; 
PROCEDURE FillCPoly (poly: PolyHendle; pp: PixPatHand1$AA 13 


Color Manager 

The Color Manager controls the task of translating an 
application's color requests to a color capable of being displayed 
by the current hardware. In order to handle this task, the Color 
Manager keeps information about the display in a device record 
known as a GrafDevice. 


GrafDevice = record 


gdUn i tNum : integer; (Unit number of driver) 
gdID : integer; (Client Id for search proc) 
gdType : integer; (Device type) 
gdITable : ITebHendle; (Inverse table) 
gdResPref ^ : integer; (Preferred resolution) 
gdSearchProc : ProcListPtr; (List of search procedures) 
gdCompProc  : ProcList Ptr; (List of complement procs) 
gdMap : PixMapHendle; (Pixel map for display image) 
gdReserved  : longint; (Reserved) 

end; 


The GrafDevice holds information concerning the type of 
search mechanism to be used for color matching and inverting, 
as well as a handle to its pixel map. 
The Color Manager sets up an initial color table for each 
GrafDevice with default values, which correspond to the colors 
defined by the original QuickDraw. Color Manager procedures 
can also manipulate individual colors in a color table, so that an 
application can "fine tune" the mapping of the program's color 
description to the color displayed on the screen device. 
Deferred Task Manager 
Because the Macintosh II supports interrupts through all six 
NuBus slots, a manager is needed to handle the interrupts in an 
orderly fashion. The Deferred Task Manager determines the 
appropriate time to service each of the requested interrupts, 
depending on the level of interrupt requested and other activity 
occurring within the Macintosh II. 
Operating System Utilities 
These three routines in the Operating System Utilities 
which provide the ability to switch between 24-bit address mode, 
required for compatibility with existing Macintosh applications, 
and 32-bit address mode allowing access to the full 32-bit 
addressing capability of the MC68020 and NuBus slots: 
FUNCTION GetMMUMode (var mode: integer); 
FUNCTION SetMMUMode (mode: integer); 
FUNCTION RestoreMMUMode; 

Note that the 68851 PMMU is needed for full 32-bit operation. 

Script Manager 

The Script Manager will normally be transparent to the 
Macintosh II application programmer, but it is used by TextEdit, 
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which is commonly called by applications. The Script Manager 
provides the means for an application to be written independently 
of the language (or script) in use which should be a particular 
boon to programs written in Japanese and Arabic languages, as 
well as those based on the Roman alphabet. 

Shutdown Manager 

The Shutdown Manager is designed to provide a consistent 
way for the Macintosh to be turned off or to be rebooted from the 
Finder as well as from within an application. It allows the system 
to perform some housekeeping prior to turning off or rebooting. 
The Shutdown Manager is contained in the system resource file 
as "INIT" resource 4, making it available to any Macintosh that 
has been booted from a system file containing this resource. 

A Shutdown Alert is defined in "INIT" resource 2 and is also 
found in the system resource file. This alert is used on a Macin- 
tosh without power-off capabilities, such as the Macintosh Plus 
or Macintosh SE. Custom ShutDown procedures may be in- 
stalled and removed through routines available in the ShutDown 
Manager. 

Slot Manager 

The Slot Manager in the Macintosh II provides the means 
for the on-board ROM and logic to communicate with cards in the 
NuBus slots. The process of sending information to and from the 
slots requires an address translation between 24 and 32 bit 
addresses; this function is provided by Operating System Utili- 
ties. The Slot Manager concentrates on interpreting the informa- 
tion supplied by NuBus cards, and arbitrates requests for bus 
mastership. Each NuBus card is expected to have a declaration 
ROM which allows the Macintosh II Slot Manager to classify it 
and communicate with the card according to its capabilities. 

Sound Manager 

The Macintosh II Sound Manager replaces the 64K and 
128K ROM Sound Driver. All previous data structures, routines, 
and synthesizers are supported in the Sound Manager, and new 
routines have been added to take advantage of the new Apple 
Sound Chip on the Macintosh II logic board. There are four 
standard synthesizers defined within the Sound Manager: 


• Note synthesizer, for simple, monophonic sounds 

e Wave table synthesizer, for monophonic or polyphonic 
sound 

• M.ID. synthesizer, for playing music on external MIDI 
devices through the serial port 

e Sampled sound synthesizer, for playing pre-recorded 
sounds 


If a programmer wishes to expand upon the synthesizers 
provided in the Macintosh II ROM, he may do so by defining a 
synthesizer or sound resource. The Sound Manager can call the 
new resources to play existing channels, using the rules defined 
by the new synthesizer. This feature permits developers the 
flexibility to develop external sound hardware via NuBus slots, 
while using the Sound Manager to provide a consistent interface 
for sound software. 

Start Manager 

The Start Manager controls (what else?) the bootup process 
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on the Macintosh II. Once power is supplied to the Macintosh II 
and control has been transferred to the ROM, the Startup Man- 
ager determines which microprocessor is present and initializes 
the Operating System Utilities, global variables, the system heap, 
and other ROM Managers as needed. 

Changes to Existing Managers 

All existing Manager Calls are supported in the Macintosh 
II ROM. Many of the changes to existing Managers are to provide 
compatibility with the new color capabilities of the Macintosh II. 
Here are some of the changes, again listed in alphabetical order. 

AppleTalk Manager 

The AppleTalk Manager incorporates significant increases 
in its capabilities and resources. Several of these changes result 
in easier programming for server, workstation, and spooler 
machines. 

Control Manager 

The Control Manager has been expanded to include color 
support with the definition of a new data structure, AuxCtIRec, 
andits corresponding resource type cctb. These structures define 
acolor table associated with the control and determine the border 
color, fill color, and text color for the control. 

Device Manager 

The Device Manager has been modified to include support 
for NuBus cards, both as boot devices, and through the interrupt 
process. 

The user-written device package added to the Chooser in the 
Macintosh Plus ROM has been extended in the Macintosh II so 
that device packages can now position the buttons displayed in 
the Chooser window. The programmer may also supply, through 
the List Manager, the list of devices to be associated with a 
particular Chooser icon. 

Dialog Manager 

Two new resource types, actb and ictb, add color and style 
information to alerts and dialogs, and dialog item lists. These 
resources are associated with a dialog or alert by assigning them 
the same resource ID as the parent ALRT or DITL. 

The contents of the color table resources are similar to those 
found in TextEdit style records: face, size, font, and color fields 
are present to specify the look of an alert or dialog item. 

File Manager 

The Macintosh II File Manager can be used with an external 
file system other than the traditional Macintosh code. The File 
Manager documentation in Volume V of Inside Macintosh 
describes the method used to integrate such file systems into the 
File Manager. 

Font Manager 

Fonts in ROM now include Monoco 9, Geneva 9 and 12, as 
well as Chicago 12. There are also 4 and 8-bit versions of Chicago 
12 and a 4-bit Geneva 9 font to increase the speed with which 
those fonts can be displayed when using 4 or 8 bit color or gray- 
scale. The fontType structure has been modified to support color 
fonts. The new font color table resource, fctb, specifies one or 
more absolute colors in the font. 

International Utilities Package 

The International Utilities Package has been extended to 
support the new Script Manager. It now includes multiple re- 
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sources within a given script, and new date and time formatting 
options. International scripts with non-Roman sorting rules may 
specify the details via hooks in this package, so that characters 
such as "а" and "4" may be treated as equals for sorting purposes. 


Menu Manager 
The menu manager has also been extensively rewritten. 
Modifications include: 


Hierarchical Menus. The Menu Manager now implements 
hierarchical menus; if another level of menu is "beneath" a menu 
item, aright or left arrow is shown next to the menu item. The user 
moves the mouse to the left or right as needed, and another menu 
"pops out" to the side of the original item. The mouse is used to 
select an item from that menu, or to go up or down to another 
menu level. Five levels of hierarchical menus are permitted, but 
they look terribly confusing if you use more than one extra level. 


Color Menus. Color menus are not implemented through a 
standard Color Lookup Table, but use a unique definition, the 
Menu Color Information Table. A distinct MCInfoRec may exist 
for the menu bar and for each menu title and item. Within each 
MCInfoRec, you find RGBColor information for the item in 
question and its background color. 


Printing Manager 
The Printing Manager has been moved to ROM. All routines are 
now available through a single trap, $A8FD, which is then 
vectored to the particular Printing Manager call. 
SCSI Manager 
The Macintosh II and Macintosh SE ROMs implement an SCSI 
"blind" transfer mode. The types of SCSI drives Apple will use 
support hardware handshaking, so blind transfer capabilities will 
result in faster transfer rates in those situations. 
TextEdit 
TextEdit records have not changed in size or structure, but they 
may now be interpreted in a different way. If the TextEdit field, 
txsize, has a value less than zero, the TextEdit record has style 
information associated with it. In that case, a handle to a TESty- 
leRec structure replaces the TextEdit fields txFont and txFace. 
This style record holds an array of "runs", each of which may use 
a different text style (font, face, size, color, line height, and font 
ascent). 
With the addition of multiple runs within a TextEdit record, the 
existing limitation of one type of font and style has been re- 
moved. Further, an RGBColor can be specified with the STEle- 
ment for each run, so TextEdit now supports color. You can 
therefore use TextEdit to write a paragraph like this 
one, which should make many programs much easier to write 
(if not easier to read). You did notice that some of these 
, While others are in red, didn't you? 
Style information can be passed from TextEdit to the application 
through a TextStyle record, which includes font, face, size, and 
color information. When the scrap is used to cut and paste style 
information, a new scrpSTElement type is used to transfer style 
and start character information. 
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Here are some new TextEdit calls: 


FUNCTION TEStylNew CdestRect,viewRect: Rect): 
$483E ; 

PROCEDURE SetStylHandle CtheHendle: TEStyleHandle; ҺТЕ: 
TEHandle); 

FUNCTION GetStylHandle ChTE: TEHandle): 


TEHandle; 


TEStyleHandle; 


FUNCTION TEGetOffset (рї: Point; NTE: TEHandle): integer; 
$483C; 

PROCEDURE TEGetStyle Coffset: integer; VAR theStyle: TextStyle; 
VAR lineHeight,fontAscent: integer; hTE: TEHandle); 
PROCEDURE TEStylPaste СҺТЕ: TEHandle); 

PROCEDURE TESetStyle (mode: integer; newStyle: TextStyle; 
redraw: BOOLEAN; hTE: TEHandle); 

PROCEDURE TEReplaceStyle (mode: integer; oldStyle,newStyle: 


TextStyle; redraw: BOOLEAN; hTE: TEHandle); 
PROCEDURE StylTextBox CtheHandle: TEStyleHandle; theText: Ptr; 
theLength: longint; box: Rect; just: integer); 


[Unfortunately, a number of limitations still remain. Chief 
among them are a 32K limit on text and problems with teScroll 
using integer offsets which cause Text Edit to crash if the number 
of lines times the line height exceeds the integer offset for the 
number of pixels to scroll. Also the limitations of integer rec- 
tangle coordinates in the destination rectangle still exits. -Ed] 


Vertical Retrace Manager 

The Vertical Retrace Manager has been changed slightly to 
take into account the flexible video interface on the Macintosh II. 

Window Manager 

А new data type, CWindowRecord, has the same structure 
and size as the old WindowRecord, except the field port is now 
defined as a CGrafPort rather than the old GrafPort. A few other 
new data types are also provided. 


Monitors 


The 12-inch monochrome monitor runs at 75 pixels per 
inch, displaying 640 by 480 pixels. This represents a screen about 
8.5" wide, and 6.4" tall, with 1.75 times more pixels than the old 
Macintosh. The 13-inch analog RGB color monitor runs at 68 
pixels per inch, but has the same 640 by 480 pixels. Both 
monitors have a screen refresh rate of 66.7 Hz, because flicker 
was still visible at the normal 60 Hz rate. The Vertical Retrace 
Manager still provides "ticks" atarate of 60 Hz for compatibility. 

After comparing both screens side-by-side, you can see that 
the color monitor is excellent, but still not quite as sharp as the 
monochrome monitor. It is still very sharp, however. We do 
believe that you could use the color monitor all day, even for 
word processing, since you could use a larger font if necessary. 
Which monitor should you order? The monochrome will ship 
before the color one, so if you are in a hurry you might choose it. 
On the other hand, the color digitized images are spectacular, and 
even color More? (version 1.1c) is quite attractive. If you need 
to do presentations, color More will be just the thing. 

You will definitely need a color monitor, if you plan on 
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writing color software. 

Several other companies have announced other video op- 
tions for the Macintosh II. For example, SuperMac has shown a 
19-inch, high-resolution color monitor connected to a Macintosh 
II, just in case you are addicted to full page displays. It also 
seemed very sharp. 

System Software 

Finder 5.4 and System 4.0 are temporary versions offering 
a fancier Control Panel, Trash Can, Chooser, and other changes, 
including many new resources in the System file. Finder 5.4 and 
System 4.1 will actually be shipped with the Macintosh II, and 
will eventually be the choice for all Macintoshes except the 
original 128K RAM Macintosh, and the Macintosh XL. There is 
reason to suspect that the new System file will contain enough 
library routines to support using the new calls to TextEdit. and 
some of the other Managers on existing Macintoshes. In this way, 
we could write programs that would run on the all Macintoshes 
with at least 512K of RAM, and still use many of these new 
features. 

LaserWriter driver version 3.4 is on the way, offering 
numerous enhancements and bug fixes. 

A/UX is a version of UNIX which conforms to AT&T 
System V, Version 2, Release 2, with Berkeley and Apple 
enhancements. You can, of course, use all the ROM calls from 
within this multi-tasking environment, and therefore write 
"proper" Macintosh programs. 


Comments about the new Macintoshes 


The Macintosh SE 

The SE is probably more important than it seems at first 
glance, because it can be expanded relatively painlessly, and 
offers better performance than a Macintosh Plus. In particular, 
the internal SCSI hard disk is considerably faster than Apple's 
external HD-20SC on a Plus. The Apple field people like the SE, 
and think it will sell extremely well. 


The Macintosh II 
Obvious strong points include: 
€ Ithas very few limitations to limit future expansion and growth 
of the product line. 


€ You can put giant display screens showing thousands of colors 
in it. The color monitors seem to be very crisp and clear. We 
will actually be able to look at them all day long without going 
blind. You can also use up to six monitors simultaneously! 


€ You will eventually be able to directly address up to 128 MB 
of RAM on the motherboard. Each NuBus card can address 
more than 256 MB (that's right, megabytes). 


€ You can add processors and co-processors that can take over 
the NuBus (80386s, perhaps 68030s next year and who knows 
what a few years later). 


€ The ROM software is designed, as always, with device 
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independence in mind, so that well-written applications 
should continue to work as the hardware progresses. 


Limitations include: | 

€ DMA was not implemented on the logic board, so this means 
that the processor still has to give disk I/O its full attention. 
NuBus cards, however, can use DMA. 


6 There is no floppy drive port, so we can't connect our HD-20s 
to the II. How do we get our data over to it's SCSI disks? We 
need an adapter to attach old HD-20s to the internal floppy 
connector - here is another opportunity for an enterprising 
individual. 


6 Many people feel that Apple needs a multi-tasking O/S to 
succeed in the workstation market, but they do not have one yet 
(except A/UX, of course). [A new Finder is under develop- 
ment, inspired by Andy Hertzfeld's Servent, which Apple 
purchased last year. Unfortunately, developer's have been 
signed to non-disclosure on the development efforts so we 
can't commenton it. Apple has been very sensitive on the issue 
of Servent and it's influence on this effort. -Ed] 


6 The price is high. Will the MS-DOS clone wars make the 
Macintosh II too expensive for business? Perhaps, but the 
Macintosh II does look cheap as an engineering workstation - 
if we write some great software for those markets. So don't 
stand there, get busy! Recent announcements by IBM make 
those products even more expensive, and the delay in delivery 
of their new OS should make the Mac II an attractive price/ 
performance alternative over the next ten months. 
Performance 
Here are some benchmark results from the Macintosh SE 
and the Macintosh II. Noted that Macintosh II graphics perform- 
ance depends on the graphics mode, with one-bit per pixel color 
(or grey scale) naturally operating faster than eight-bit per pixel 
color. 
Theraw numbers, in ticks, are given in the table below. The 
chart that follows has a vertical axis of Time, relative to the 
Macintosh Plus as a standard. 


SE 11 
256 colors 


Prodigy 4 


(2 colors) 

Integers 174 40 

Reals 537 104 
Extended 317 57 
Transcend. 559 63 or 14*** 
Sieve 442 116 

Lines ; 265 244 C170) 
Windows 356 165 (99) 


One prototype Macintosh II gave a benchmark result of 63 
ticks for a program that computes transcendental functions, such 
as logarithms, cosines, arctangents, and square roots. Another 
prototype gave a much shorter time of 14 ticks. Since this test 
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depends on SANE's use of the 
68881 math co-processor, we 
need to run these tests again after 
the system software is finalized. 
We show the longer time in the 
chart on the right. 


What do these numbers 
mean? Here are some tentative 


conclusions: | à "B | T] i TT ЕШ : T 
HE ЕЕ ЕШ НЕЙ 


1. The SE is up to 15% faster than Integers Reals Extended Transcend. Sieve Lines Windows 


the Macintosh Plus. This is Ш Mac Plus ЕН Mac SE ЕН маси (256 
because the video circuits no colors) 


longer steal as much processor 
time for RAM refresh. AI- 
though we did not test the hard 
disk, other tests indicate that 


Mac II (2 О Prodigy 4 
colors) 


the SE's hard disk performance may be up to two times faster Other support, such as MPW Pascal version 2.0, is on the way. 
than that of a Macintosh Plus, due to improvements in the SCSI Note however, that SANE is more accurate than the 68881 
driver in the SE. alone due to some problems with certain functions in the math 
chip. If accuracy is important, you might want to use the more 
2. The Macintosh П is similar in performance to a Macintosh Plus accurate algorithms in SANE for SINE and COSINE func- 
with a Levco Prodigy board. This is reasonable, since both tions rather than calling the 68881 directly. 
have a 16-MHz 68020 with a 68881 math co-processor. The 
Macintosh II is often 4 to 5 times faster than a Macintosh Plus, | 4. Other tests indicate that the Macintosh II has much faster hard 


but may be 50 times faster on some number crunching. Again, disk performance than other Macintoshes, running up to three 
our test results are not clear in this area yet. times faster than a Macintosh Plus. It is not as fast as it might 
be however, and early indications are that if the II has any 
3. The number crunching tests reflect the Macintosh II's use of a weakness at all it might be in this area of disk access. 
newly written SANE package. SANE will use the math co- 
processor if it is there. If you were to write your program All in all, the Macintosh II looks like a superior computer - 


directly using 68881 instructions, you would see even better one that presently offers the best combination of performance, 
performance. One Apple test showed that direct calls to the | price, and superior software. We think that you will like it. 
68881 were about 6 times faster than using the patched SANE. 
You can write instructions to access the 68881 with MPW Сем! 
Assembler, а version of Consulair C, and Absoft FORTRAN. 
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Developer's Conference 
The Mac II Hardware 


Apple held it's Spring Developer Conference this 
week at the TechMart/Doubletree Inn in San Jose, just 
as IBM announced their new PC System 2 computers. 
In fact, the six hundred Mac and Apple developers had 
to cross through the reception area for the big IBM 
announcement to get to the conference rooms where 
the new Mac II hardware was being discussed. A few 
Mac fans slipped off their Apple badges and infiltrated 
the IBM crowd to carry off the product descriptions of 
the Mac-alike PCs. The new IBM machines look very 
much like the Mac II, having 256 colors out of 250,000 
even! Of course the Mac II with color quickdraw uses 
16 bits each for the blue, red and green, making a48 bit 
color selection, which allows 16 million color combi- 
nations, using 24 bit color table entries. The number of 
colors available at one time is dependent only on the 
amount of memory on the NuBus video card, which in 
24 bit mode can be up to 1 megabyte per NuBus slot. 
The initial Apple video card (and SuperMac Spectrum 
card) allows 256 colors from the pallette at one time, 
using an 8 bits per pixel index, but the intricate color 
quickdraw is far superior to the modes of the IBM, 
allowing sophisticated mixing of color into new col- 
ors, and animation of the color tables. Each window 
retains its own color table, which are switched as each 
window becomes active by the color manager. The 
generalization of color quickdraw means it will sup- 


port new video hardware well into the future without . 
any Changes to current application software. By comparison, the 


IBM implementation is grammar school stuff. The generaliza- 
tion allows applications to specify color in RGB space, a cube 
structure 16 x 16 x 16. The RGB color is then matched to a best 
fit for that color in the video card's color table automatically. 
Better video cards just make the match that much closer to being 
exact. À color picker utility and improved control panel access 
allow the user complete freedom to configure the desired 256 
colors from the pallette. 

Multiple video displays are automatically supported by the 
window manager and color manager so that you could set up a 
Mac II with three video displays and move windows across 
screen boundaries. When future multi-tasking Finders are ready, 
each window will be an active application, switchable by a 
simple mouseclick. With alternative CPU cards acting as NuBus 
masters, each window could also be an emulation of another 
computer architecture as well. It may be possible to open an MS/ 
DOS window on one video, Mac Finder on another, and Unix on 
yetathird, with complete movement of information between the 
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three. In fact, the Mac II may be the most flexible computer ever 
designed. No doubt a complete Apple IIGS emulator card will 
arrive from someone in the near future that would allow the Mac 
II to run Apple II software without modification. 


(32 meg max) 


ADB 2. ға /аувсага, 
— — — mouse) 


(Appletalk) 
serial 
ports 


Mac Il Hardware 

The most fascinating part of the conference was the descrip- 
tion of the Mac II hardware. This is truly a beautiful 68020 single 
board computer implementation as shown in figure 1, with every 
consideration given to the on-going development efforts both 
within Apple and from Motorola. The Integrated Woz Machine 
has been reduced even further so that now it is a tiny custom IC. 
The IWM is socketed to allow an upgrade path for Sony 1.2 meg 
disk drives and alternative encoding schemes in the future, both 
being actively pursued by Apple engineering. In fact, the real 
message of the conference may have been the confidence that 
Apple is designing products on a continuous upgrade basis, rather 
than on the shotgun approach of the past. 

24 versus 32 bit Mode 
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Oneareaof confusionis the memory map. On the Macintosh, 
the 68000 allowed 24 bits of address space. The memory man- 
ager used the upper 8 bits of master pointers for various flags like 
whether or not the relocatable block was locked or purgable and 
so forth. Many Mac applications check these flag bits directly 
although they aren't supposed to. The result is that in 32-bit mode, 
many Mac programs bomb because they try to make use of the 
upper 8 bits of address space. So Apple made up a simple 
mapping controlled by a custom memory management chip 
called the HMMU, which selects between 24 bit mode and 32 bit 
mode from a switch signal in the VIA2. A trap allows application 
programs to switch back and forth. Apparently all the ROM 
routines have been cleaned up so they will work in 32 bit mode 
except the memory manager. Hence, normal Mac mode applica- 
tions will run in 24 bit mode on the Mac II, which allows 8 
megabytes of address space on the motherboard and 1 megabyte 
per each of the 6 NuBus slots. However, programs can also 
switch to 32 bit mode, gaining full access to the address space of 
the 68020 (4 gigabytes!), allowing far greater memory capacity 
in both the motherboard and in the NuBus slots. In 32 bit mode, 
up to 128 megabytes can be supported on the motherboard, and 
up to 16 megabytes per NuBus slot as unique address space. An 
additional "super slot" scheme can support up to 256 megabytes 
per NuBus slot although the application must check that no other 
NuBus card is currently using the super slot the card selects. 
Apple is committed to phasing out 24 bit mode and promises to 
upgrade the memory manager as third-party developers upgrade 
their programs and stop using the flag bits in handles. The 
Motorola PMMU also does this 24 bit mapping when it replaces 
the HMMU, but in addition to this simple switch, provides the 
full page memory management functions required for 32 bit 
address space so that a full-featured multi-tasking operating 
system like Unix can be supported. It is expected that the current 
Finder will migrate to a quasi multi-tasking status in the very near 
future and in fact, the 600 developers were being allowed to 
receive advance information on a non-disclosure basis at the 
conference. A list of do's and don'ts is being provided developers 
so that applications can be made compatible with such a multi- 
tasking environment. 

NuBus 


Each NuBus card contains a configuration ROM that allows 
the card to be plugged into any slot, and configured accordingly, 
eliminating jumpers or switches found in other bus systems. 
Cards may be either slaves as in video cards or masters as in 
another CPU card. Each card can communicate with each other 
and within the complete 32-bit address space of NuBus. Commu- 
nication with the Mac II bus and the 68020 is controlled through 
an arbitration scheme that allows fair access to the bus for all 
cards. DMA between NuBus and the Mac II bus is not supported 
however. In 24-bit mode, quickdraw access to a NuBus card 
allows up to 1 megabyte of the slot's 16 megabyte address space 
to also be visible to the 68020. The Macintosh II is actually 
another NuBus slot itself (slot 0). An extensive list of slot 
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FFFF FFFF 
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per slot 
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FF FFFF 1 Meg 
EF FFFF 
ЕЗ 

MEUS 256 Meg 
oe реге per slot 
8F FFFF 1 Meg 
80 0000 super slot 
7F FFFF 

8 Meg 256 meg 
RAM IO 
ROM 

00 0000 


24 BIT ADDRESS SPACE 


1 Gigabyte 
RAM 


32 BIT MODE 


0000 0000 
Fig. 2 Memory Maps 


manager trap calls controls communication between the NuBus 
card's configuration ROM and the Mac II. Unlike previous Mac 
family computers, the Mac II contains extensive hardware docu- 
mentation on how to design a NuBus card and firmware. 


Video Card 


The first Apple NuBus card is a video card that demonstrates 
how the NuBus works. As mentioned previously, color quick- 
draw generates digital information of 16 bits each for red, blue 
and green. It is the video card's responsibility to generate the 
video signal from this information. A frame buffer controller is 
implemented as a CMOS gate array with control registers to 
define the video array configuration. With 512K bytes of video 
memory on board, the card allows an 8 bit color depth per pixel, 
thus generating 256 colors at one time within a resolution of 640 
pixel screen width. The frame buffer controller drives the color 
lookup table, which controls which 256 colors to select from the 
16 million possibilities, and generates the analog red, green and 
blue video signals. The video RAM array uses ICs with a built- 
in shift register and separate serial port for video data to maxi- 
mize the speed with which the 68020 can modify video memory. 

The color lookup table takes digital video information from 
the frame buffer controller and passes it through a RAM based 
color table to three 11-bit DACs to generate the RS343A compat- 
ible RGB video signals. The color table can be modified dynami- 
cally by the 68020 to animate the video screen by changing the 
current set of 256 colors available. The Pallette manager arbi- 
trates this color lookup table scenario so that multiple windows 
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and DA's don't contend with each other over which color table 
will be active at any one time. Video cards with additional 
memory could increase either the resolution or the color table 
possibilities without any effect on applications. Additional video 
cards are linked by the window manager to be extensions of the 
same active GrafPort, again, independent of the application. 


Sound Chip 


The custom sound chip is also socketed so it can be upgraded 
in the future. The current sound chip is able to sample audio at 
44KHz, which allows a wider bandwidth than the previous limit 
of the 22KHz sampling rate in the Mac Plus. There is, however, 
alow pass filter in hardware that starts rolling off at 7.5 KHz. In 
future versions of the sound chip they will use a switched 
capacitor filter to notch filter the sampling clock which will allow 
for an improved high end in the audio response. They also plan 
toexpand the 8 bit linear coding of the sound samples to a pseudo- 
12 bit digitization. This will make for better signal to noise ratio 
and distortion figures. If Apple makes these improvements in the 
sound chip, it will be up to the level of currently available 
"sampling" music synthesizers. The output jack provides for a 
stereo output to an external amplifier and speaker set. 

One change in the Mac II is that the external floppy disk 
interface is not provided. The Mac II box has room internally for 
two floppy drives and a hard disk. Another feature from the Lisa 
days is that the power switch is programmable. A clock NuBus 
card could turn the Mac on ata pre-set time, perform an operation 
like logging a call and saving data to disk, then shut off the Mac 
when the call completes. The video display is also controlled by 
the Mac II switch so the entire computer can be turned off and on 
under program control. 

Another point worth noting: the alternate sound and video 
buffers are not supported, since the video is unbundled from the 
CPU and main memory. 


Compatibility Issues 


Applications should observe some obvious precautions to 
runon the new machines. Neither the video address space nor the 
application heap space should be thought of as either fixed in size 
nor in location as both will change. The system heap may also 
become dynamic, managed by a future operating system for 
multi-tasking and as such should not be used by an application. 
Flag bits for handles may be moved out from the handle itself to 
allow full 32 bit addressing for relocatable blocks. When this 
happens, the appropriate trap calls to lock and unlock handles 
will change, so applications should check flag bits through traps 
rather than directly themselves. Since system timing will change, 
delays should be done using the Delay proc rather than in timing 
loops which depend on the current clock speed of the machine. 

Some programmers declare data using DC statements in their 
programs and then modify those locations. This won't work on 
the new machines because of the memory management and 
separation of code and data blocks. Data should be declared 
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global with the DS command and allocated on the stack or in the 
heap in relocatable blocks rather than within the code block itself. 

Much of the hardware of the Mac II may change in the future 
so access to hardware should be done through the toolbox 
routines. This includes the IWM and sound chips, which are 
socketed and sure to be upgraded in the future, as well as VIA2 
which may disappear altogether into a custom NuBus manager 
chip. Presently VIA2 manages most of the interrupt functions of 
the machine, and so is an obvious target of improved integration 
and memory management in the future. The Enivrons trap call is 
being expanded to allow machine identification and this is the 
proper way to figure out what you are running on. The Mac 
parameter will identify a classical Mac, Mac SE or Mac II. The 
version parameter will identify the ROM setas either64K, 128K, 
SE or Mac II ROMS. Apple is trying to develop a Universal 
System File that can run on all machines, making identification 
of system file goodies unnecessary. If this can be achieved, it 
would greatly simplify life with multiple Macs. The new trap 
calls of the SE and II would be available as trap patches in the 
system file to the Mac Plus so applications need not worry about 
which Mac is running. However, this cannot be done for color, 
which is only available on the II. By supporting SANE, applica- 
tions would automatically get improved performance on a Mac 
II without having to code special cases for the 68881 being 
present or not. The Universal System File is expected to ship for 
all Macs with the Mac II. 


Shared Environments 


Just when things were starting to become clear, not only do 
new machines and new ROMS make it cloudy again, but new 
ways of doing things also confuse the issue. With Apple Share, 
applications must worry about multiple users of a single program 
on the net. Applications should plan both for shared environ- 
ments and multi-tasking as future extensions of the Mac design. 
To be compatible with multiple users double clicking on a 
program in a shared environment, the application must not write 
configuration information to it's own data or resource forks. In 
fact, the resource manager is something to be avoided whenever 
possible when writing to disk by the application as it is especially 
bad for both shared and multi-tasking situations. Files opened by 
an application should remain open until the application ends thus 
preventing them from being changed by another user. The file 
manager has new error messages indicating the status of existing 
files so that shared data files are not corrupted by multiple users. 
A new tech note describes how programs should operate in a 
shared environment. 

In general, everything you knew before is now the wrong way 
to do it in a shared environment. Here are some example of 
traditional ways of working that no longer work. A memory 
based application opens a file, reads the contents, closes the file 
and lets the user modify the data. When the user saves, the file is 
opened and the new data written out. This won't work with 
multiple users since another application could have opened the 
file in the meantime and made modifications that would be 
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destroyed by the close operation. The solution is to open the file 
and leave it open until done, preventing another application from 
modifying it. 

Another well used scenario is to open the file, read it and close 
the file, then create a new file and copy the finder information to 
the new file when the user selects close, deleting the old file and 
renaming the new file. This bombs because another user could 
have already saved and deleted the old file by the time the first 
user is ready to close. The solution is to get the Finder information 
at open time, then check for file errors when closing in case the 
file has already been deleted or renamed. However, the tech note 
recommends that this so-called switch approach is not the best 
way to handle files. 

The final situation is disk based applications. They should 
keep the file open as either read or write status, locking out other 
users until the file is released. When the file is closed, the 
temporary file holding the changes can be written to the primary 
file and the file closed. An alert should be posted if the user tries 
to open a file in use by someone else. If your application supports 
concurrent access to a shared data file, you'll have to invent a 
reliable locking mechanism yourself. 

Language Support 


In the last session of the conference, developers heard from 
a number of vendors on the status of popular development 
systems. MPW and MacApp are undergoing revision to version 
2.0 and 1.1 respectively. Object Pascal will also be released as 
version 2.0 as well. With this version, MPW gains a Mac like 
friendly interface that eliminates typing file names! This next 
release of both MPW and Object Pascal 2.0 seem particularly 
robust and powerful with many new features developers have 
requested including file markers. MacTutor plans to start using 
these new versions on a more extensive basis in articles published 
in MacTutor. 

The popular Lightspeed products are also being revised to 
Work on the Mac II. Both C and Pascal will have new versions in 
the same time frame as the Mac II begins shipping. Another 
major release of Lightspeed Pascal is expected this summer that 
will greatly expand on the already powerful debugging features. 

Paul Snively demonstrated a version of TMON that works on 
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the Mac II. Icom Simulations is working on anew, more powerful 
TMON for release late this year. 

One oversight at this session was the fact that Steve Jasik was 
not invited to discuss his new debugger for MacNosy. His 
debugger will also be Mac II compatible. 

TML announced a new version of Modula 2 that койа 
68020 code and should be a welcome addition to the Мас 
language family. MacTutor has asked TML to supply us with 
more details which we will report to you in an upcoming issue. 
They are also continuing to update their Object Pascal. 

Aztec C has greatly modified their product to both work on 
the Mac II and continue to support many of the Unix features that 
make this C product popular. Now that Unix is an Apple spon- 
sored product on the Mac II, Aztec C may become much more 
influential in Macintosh program development. Look for major 
advances from this re-vitalized product. 

Consulair is now shipping MDS 2, which they have taken 
back from Apple. We expect Consulair will now actively support 
MDS and keep it up to date with the new Mac II traps. (If they 
don't we'll raise a big fuss!) 

The conference concluded with statements by Apple that 
they expect the September time frame to be an important one for 
new productannouncements and encouraged developers to shoot 
for the summer Apple World to release new products. It is 
expected that the Mac II will be shipping in quantity by then and 
Apple wants to show that you can do iton a Mac today rather than 
wait for an IBM tomorrow. Apple is expected to release some 
significant new products at that time. A final tidbit at the 
conference was the base address of an interesting PICT in the 
Mac SE ROMS: $41D898. Dump this out and you'll know why 
the SE and the Mac II both have 256K ROMS even though the 
Mac II contains color quickdraw. Apple still retains some corpo- 
rate sense of humor from the Steve Jobs era. 

Kirk Austin contributed to the sound portion of this article, for 
which we are grateful. He is preparing future articles on the 
new sound capability for MacTutor. 
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Conference Report 
MacHack '87 


There were twice as many attendees as last year and things 
were generally more professional, but the untamed spirit of the 
original MacHack remained strong. Some of the best Macintosh 
programmers like Darin Adler of Icom Simulations and Lutus 
Langens of Ann Arbor Softworks were there, as well as interest- 
ing and influential folks like Doug Clapp (MacUser columnist), 
David Smith (MacTutor editor), and David Lingwood (Apple 
Programmers and Developers Association Executive Director ). 
The conference was sponsored by the Mac Technics users group, 
The University of Michigan School of Education, and Broadacre 
Network. MacTutor, Odesta, Kinko's Copies, Rent a Byte, and 
Apple Computer also provided important material support. 
MacHack provided many opportunities to talk to other Mac 
programmers and exchange ideas. Several jobs were offered 
during the conference and a few unreleased products benefited 
from algorithms and data structures gleaned from code bashing 
sessions and presentations. 

My impressions and recollections of the conference, which 
are necessarily biased by which sessions I attended and my own 
strong personal opinions follow. I will present events in approxi- 
mate chronological order and summarize some of the most 
important things to emerge from the conference at the end of this 
article. I would like to thank Doug Houseman of Small Systems 
Guild and Aimee Moran and Carol Lynn of Expotech for their 
professional and often extraordinary efforts towards making 
MacHack 87 a success. I also want to thank Scott Boyd of the 
MacHax™ group for allowing me to incorporate some of the 
contents of his conference description which appeared on 
ARPAnet the week after the conference. 


Pre-conference Workshop 


The week began Monday, June 8th with a two day pre- 
conference workshop on Macintosh programming. The plan was 
to provide new and moderately skilled Macintosh programmers 
with an overview of the organization and interactions of most 
ROM Toolbox Managers. This required that the philosophy, 
data structures, routines, and calling sequences for twenty some 
major topics be explored in 12-13 hours of presentation time. 
The best way to insure the workshops success would have been 
to have David Wilson, the instructor and creator of Apple's 
Macintosh Programming Seminar series, serve as instructor. 
Unfortunately David Wilson hada schedule conflict, and the best 
chance for making the workshop worthwhile seemed to require 
a practiced presenter and a lot of handouts and sample code. 

Since I first took Wilson's course in 1985 I have taught a 
similar introduction to Mac programming in the Ann Arbor area, 
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language none limited moderate extensive 
Pascal 3% 16% 49% 32% 

С 25% 22% 318 22% 
Assembler 173 428 288 14% 
BASIC 6% 185 39% 36% 
For th 80% 12% 0% 8% 
Mac experience none some a lot 
MacPaint/MacWr i te 0% 95$ 5% 

other epplications 0% 95% 5% 
Macintosh programming 18% 19% 3% 


Fig. 1: Pre-workshop experience - 38 responses 


mostly to people from the University of Michigan or MacTech- 
nics members. We decided to update the course handouts, 
resulting in about 300 pages of material, and to fit three days of 
instruction into two days by eliminating all labs and hands on 
activities. This necessarily limited the usefulness of the material 
to those attending, but the idea was to give programmers a broad 
understanding of the techniques and issues surrounding Macin- 
tosh programming. To that extent the course succeeded, but I lost 
my voice and virtually every workshop evaluation form called 
for more time and labs. There were also a few glazed eyes among 
those attending, but Mac programming can be alittle overwhelm- 
ing at times. See figure 1, pre-workshop experience. 


Forty seven people attended the workshop, and all 50 copies 
of the course materials were distributed. The workshop was 
video taped, and if the 12 hours of material can be edited into 
something useful it ora transcript will be made available to those 
interested. 

Strong demand for a low cost Mac programming class which 
parallels Apple's seminars has been established. The MacHack 
Steering committee has asked for several quarterly three day 
Macintosh Programmer Training workshops to be held in Sep- 
tember, January, April, and before MacHack 88 in June. They 
also requested that the cost be kept below $300, substantially less 
than the $1000 that Apple charges, and a language independent 
approach will be maintained. David Wilson and David Feldt will 
again be invited to participate. 


Startup address 


Doug Clapp writes a column for MacUser and is a well known 
Macintosh commentator and author. Clapp had many things to 
say, butafew of them made alasting impression on many of those 
attending and seta tone which carried across the remainder of the 
conference. He talked about programmers designing software 
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for the journalists instead of users, emphasizing features that 
make good ad copy and comparison charts but provided little or 
no utility for the user. Clapp suggested several ways computers 
were being used to address problems like world hunger, and 
challenged programmers to look for ways that they can make 
positive contributions whose value is not necessarily measured in 
dollars. 

Clapp also talked about how he became a writer and about the 
MacBots project. In reference to his predictions about the 
potential for the microcomputer revolution Clapp said; “Т 
thought that when computers were available to new, creative 
individuals we would see new insights and solutions to world 
problems. Instead we mostly seem to have a lot of public domain 
and shareware disk utilities." 

Doug Clapp stayed for the entire conference, and at several 
points exclaimed to others; “It may seem strange, but I’m really 
having fun. Really!" We were all impressed by Clapp, and are 
wondering if other columnists might also be such nice people? 
I'm looking forward to seeing what the slick paper Macintosh 
press has to say about hard core Macintosh programmers as- 
sembled in large numbers and high densities. 


ROM versions 


This session was intended to be a panel of Mac developers and 
Apple reps discussing how to achieve application compatibility 
between 64K, 128K, 162K (Mac SE), and 256K ROMs. With 
help from a few knowledgeable individuals in the audience we 
discussed the implications of Apple Tech Note 44117 (the one 
with all the “Thou shalt nots”) and Apple's official compatibility 
guidelines. 

Several specific steps were offered which could help applica- 
tion developers deal with the compatibility problem. These ideas 
included: 

• Write ValidPointer() and ValidHandle() routines to check 
pointers and handles for reasonability before passing them to a 
ROM routine. Pointers are reasonable if they aren't NULL and 
point below the top of physical memory. Handles are reasonable 
if they are valid pointers and point to valid pointers, (in addition 
the most significant byte of a master pointer may have bits set 
which must be ignored when testing validity). A code sample of 
how to do this is given below: 


/* Lightspeed C 2.01 source, based on the ValidPointer(), and 
ValidhandleC) routines in the Programmers Extender Vol 1 by 
Invention / 

Software Inc. (Note that comments are edited for publication, 
and multi-line comments are not LSC compatible.) */ 


Boolean ValidPointer(P) 
Ріг P; 


if CCP == NULL) || (Clong>P & 1L2) 
/* if pointer is NULL or odd */ 
return(FALSE); /* then pointer is definitely bad! */ 


/* In my opinion test for null should be ommitted, indexing 
into an array of characters (bytes) could result in а valid 
pointer to an odd address */ 


~ 


126 


/* another test which should be added here is a check to see 
that the pointer is not above the tom of RAM, but MemTop() 
does not return the correct value when running under switcher 
or servant. */ 


els 
) 


Boolean ValidHandleCH) 
т? Н; 


е 
returnCTRUE); /* else pointer is potentially valid*/ 


Ptr Р, 


if (ValidPointerCCPtr2H22 ( 
/* the handle dereferenced is OK */ 
P = (Ptr)CClong)(*H) & 9x0QFFFFFF 2; 
/* mask off the master pointer status bits */ 
if (ValidPointerCCPtr2P)) 
/* the pointer pointed to is OK | */ 
return( TRUE); 
/* then Handle is potentially valid */ 


) 
return(FALSE ); 


/* Handle doesn’t point to a pointer */ 


* Use CurrentResFile(), Environ(), and other ROM routines 
to get information for an environment data structure which stores 
information on the applications own resource fork path refer- 
ence, Macintosh model, ROM version, top of memory, CPU, 
math coprocessor, etc. Use this information in determining 
which ROM calls to use to accomplish a task or alternately to 
disable program features which cannot work on older ROM 
machines while leaving users access to those that will work. 

[Note: In MacTutor's opinion, it is not necessary or desirable 
to extend this compatibility to 64K ROMS, as Joel West's article 
in this issue makes clear. -Ed] 

е Sacrifice speed and elegance for compatibility. Most of the 
application developers who have run into trouble got there 
because they knew a better way and didn't want to be limited by 
the ROM. These folks have been plagued by incompatibility and 
user complaints whenever Apple introduces a new machine 
while those with greater dependance on the ROM have witnessed 
their programs grow steadily faster and smoother as Apple has 
improved the quality of the ROM code. 

* Use GetWMgrPort() to reference into the screen bitmap 
record to determine screen size at runtime. This is equivalent to 
using the screenbits.bounds rectangle, but works from within 
code resources and desk accessories where no global variables 
are accessible. 

e Think about not covering up the 40-50 pixels along the right 
edge of the screen with windows, icon pallets, etc. to allow the 
Finder's disk icons, trash can, etc. to show through when an 
unannounced enhancement to the Finder makes such things 
possible. 

Tools 


At the same time a session was taking place where a heated 
discussion of MacApp, Macintosh Programmers Workshop, and 
other topics was fielded by Jordan Mattson of Apple, Leonard 
Rosenthal of Davka, David Smith of MacTutor, and Rick Tho- 
mas of Personal Bibliographic Software. Since the conference 
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was attended by mostly full-time developers, the concerns 
voiced reflected many of the problems experienced in the day-to- 
day process of getting ideas out of programmers heads and into 
Macintosh programs. The session quickly moved from discus- 
sion of the available tools and environments to the problems 
developers have with the tools, and general Apple bashing. 

It became apparent that MPW is widely used, and as with 
most development tools, a love/hate relationship exists. Many 
of the comments involved improvements to MPW. Other com- 
ments focused on how to improve the working relationship 
between developers and Apple's tech support and system soft- 
ware people. Apple's only representative at the conference, 
Jordan Mattson, took careful notes and suggested that an official 
"Bash Apple Session" on the final day of the conference might 
provide a better forum for such discussion. The proposal was 
well received and the session scheduled for 9 AM Friday morn- 
ing. Mattson displayed quantities of energy, listening, and 
leadership skills equivalent to several people. His presence at 
MacHack was so professional and skilled that several conference 
evaluations indicated that many attendees believed that there 
were many, not one, Apple representative. We all hope that 
Apple appreciates this guy. 


Wednesday afternoon 


The first of the lunches was all right, and most folks fears 
about the quality and quantity of food were put to rest for the 
remainder of the conference. Sessions on Marketing aspects 
where David Lingwood of APDA showed how to prepare a 
marketing segmentation and marketing plan, Languages, and 
several case studies went well, but the most interesting and 
controversial session of the afternoon was clearly Debugging 
with Steve Jasik of MacNosy fame and Paul Snively of Icom 
Simulations (TMON). Some said it was a big Nosy commercial, 
some complained because the session didn't last longer, others 
said Paul told them more about TMON than they wanted to hear, 
but virtually all attendees managed to get themselves worked up 
about one thing or another. 


TMON case study 


Waldemar Horwat, the principle author of TMON, presented 
the TMON Case Study. He was accompanied by Darin Adler, the 
author of the popular Extended User Area. Paul Snively rounded 
out the group. Waldemar related some fascinating things about 
the development of TMON. For instance, he wrote the entire 
program in assembler on the Lisa. That is to say that he wrote the 
entire program before he assembled it even once. After every 
assembly, he advanced the version number. Another interesting 
fact is that Waldemar was fourteen when he started coding 
TMON! 

The Ann Arbor Softworks party 
(Hacker's version of one-upsmanship) 

My vote for funniest hack of the conference goes to some guys 

from Texas who created a special application with a silver surfer 
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icon and tucked it away in an obscure folder on one of the 
accessible hard disks. The first to bite were a few ace Mac 
programmers at Ann Arbor Softwork's hackers-only party 
Wednesday night. When launched, the nefarious app would 
come up with the non-disclosure do not distribute dialog of the 
real beta Silver Surfer and wait for a mouse down event. No 
matter where the user clicked, the app would beep three times and 
put up an alert saying “You didn't click in the secret spot". The 
obvious response to such security measures was TMON! A few 
minutes later when no rectangles or regions as target areas could 
be found a second ace Mac programmer was called in. “What if 
they patched SysBeep()?” he mused. Ofcourse! Sysbeep()! And 
it turned out that SysBeep() had indeed been patched, plots within 
plots! It wasn'tuntil the numberof code segments (2) and the size 
of the app (14K) were consulted that the truth was revealed. The 
real silver surfer (AKA 4th Dimension) is about 642K. “It’s а 
hoax! It's justa hoax!" and poorly stifled laughter were heard for 
some number of minutes thereafter. During the following days 
afew other folks who probably should have known better stayed 
up until 4 AM attempting the same access, but without as 
appreciative an audience. 


4th Dimension database 


The author of this article, still hoarse from the pre-conference 
workshop, presented a two hour overview of the latest high end 
Macintosh database management system, 4th Dimension. This 
product is being brought to market by ACIUS (the company Guy 
Kawasaki and Scott Knaster quit Apple to run) after several years 
of successful use in Europe and over a year of Apple supported 
enhancements. The idea presented was that most Macintosh 
developers would be better off with such a high level develop- 
ment tool and less knowledge of the ROM. This point was hotly 
debated, as were many of the user interface and implementation 
decisions of 4th Dimension’s designers. The audience reactions 
ranged from religious ecstasy to claims that 4D was clearly the 
most over-hyped product of the year. 4D is an important and 
complex product which cannot be fully described or appreciated 
in a period of a few hours, but it was generally agreed that it and 
enhancements to Helix and Omnis 3 were broadening the tools 
and options available to Macintosh application developers. 

The 4D presentation was followed by a Battle of the Data- 
bases panel including Daniel Chiefetz who is the President of 
Odesta (Helix), David Feldt for ACIUS (4th Dimension), and 
Tom Gottenheimer for Blythe (Omnis 3+). The comments were 
basically cordial and positive, but issues of technical support, 
warrantied performance of development tools, and open disclo- 
sure of known bugs elicited some strong opinions from panelists 
and the audience. Of particular interest to me were the descrip- 
tion of a Helix access protocol which would allow microcom- 
puter front ends to communicate with a variety of database back 
ends over AppleTalk, Ethernet, and other communications 
media. The evolution of such protocols offers a promise of 
flexibility and compatibility for all developers while at the same 
time opening the floodgates of Mac to mainframe communica- 
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tion between information interfaces and servers. 

The idea of a bulletin board or computer conferencing system 
with which developers could communicate and exchange bugs, 
hints, source code and other information had already been 
discussed at several previous sessions, but the need and possible 
structure for such a system crystallized and gained momentum 
during the discussions arising from this panel. Possible roles for 
Apple, APDA, and development system vendors such as data- 
base and compiler companies were explored, and several indi- 
viduals such as Jordan Mattson of Apple and David Lingwood of 
APDA indicated a willingness to work towards a concrete 
proposal. More on this important topic below. 


Bash Apple session 


A special “What could Apple do better or differently’ session 
was held bright and early Friday morning. Decorum was main- 
tained by a combination of media intimidation (the session as 
videotaped for later viewing by Apple) and a moderator wielded 
baseball bat. I have rarely seen as well behaved a group of 
Macintosh developers, but important problems and issues came 
out none the less. The session began with Jordan Mattson of 
Apple explaining the structure of the developer products group 
and a few issues he felt were key to Macintosh developers 
success. 

Jordan Mattson (Apple): “Ве internationally compatible... I 
think we have the best software in the world right now. We have 
an opportunity to go into other countries and sell that software... 
There is an enormous marketplace there, the trouble is we get fat 
and sassy. We think we have the solution, we have good stuff, but 
we don't go the extra step... Right now wehavethe best software 
in the world, but at one time we had the best machine tools in the 
world, and the best automobiles in the world." 

The issue of quality, on time documentation available at the 
same time as new development tools was mentioned, and Apples 
commitment to doubling the size of the Developers Tools group 
discussed. 

Darin Adler (ICOM): "There seems to be a rather informal 
formula for deciding what kinds of information developers need 
and what kinds they don't. I think you need to think more 
carefully about those decisions." 

David Feldman (ICOM): “Will you (Developers Tools 
group) act as a court of appeals? Right now we have a problem... 
If tech support decides not to give a certain piece of information 
out your kind of stuck." 

Frank Alviani (Odesta): “We live in an uncertain kind of 
world all the time. Getting tech notes saying “Hi! Everything you 
are doing is aboutto become illegal is very disturbing. If we were 
able to be not just in a reactive mode, but in a corrective mode..." 

(Feedback before a decision is made, not afterwards) 

Jordan Mattson (Apple): “We came up with an idea... to 
establish a bulletin board orconferencing system where we could 
have discussions like that. How many people would be interested 
in such a system?" (Virtually every hand in the room went up). 
"How many people think that it would be useful and improve the 
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quality of the Macintosh ROM?" (Every hand in the room was 
raised). 

Darin Adler (ICOM): “I have to say that I’m not all that 
unhappy with the way technical support has been handling 
things. Unfortunately the kinds of bugs that developers are likely 
to find require atwo way communication and a simple bug report 
form is able to obscure what is actually there. An engineer will 
look at it, think that he understands, and say ‘This isn't really a 
bug'. I find this happens particularly with the kind of bug a 
developer finds in a piece of software as opposed to the kind a 
user finds in a piece of software. 

“I would say that the current bug reporting scheme is totally 
inadequate. If someone at Apple finds a bug it will be corrected 
because there was two way communication, and when somebody 
outside the company reports a bug there is a lower chance it will 
be fixed. Maybe this whole idea of a bulletin board and better 
communications can be used to address that." 

David Lingwood (APDA): “I named APDA, against the 
other possible choice which was the Apple Programmers Club, 
very purposefully. Ап association pushing for professionalism, 
and we clearly want to be more than just a distribution house for 
Apple Computer... The kinds of things your talking about here, 
developing a professional communications network are the rea- 
son I got involved with APDA in the first place. We want to be 
closely involved in all this development... You folks are on the 
firing lines and know alot more about these products than we do. 
Unfortunately we don't do technical support for MPW. Unfor- 
tunately nobody does technical support for MPW. This is 
something we and Apple will have to talk about." 

Other important issues were discussed, but the consensus of 
the group was that an electronic conferencing system allowing 
Apple and Macintosh developers to engage in a two way dialog 
on bugs, compatibility issues, system software, and other topics 
would be of major value. Jordan Mattson proposed a core group 
of three to make sure that progress was made on this proposal. 
For further information or to volunteer to help with this important 
project contact one of the following individuals; 

Jordan Mattson, Apple Computer Inc, 20525 Mariani 
Avenue, MS: 27S, Cupertino, CA 95014 (408) 973-4601 
(AppleLink: Mattson1) 

David Lingwood, Apple Programmers and Developers Asso- 
ciation, 290 SW 43rd St., Renton, WA 98055 (206) 251-6548 
(APDA, attention David Lingwood) 

David Feldt, Broadacre Network Inc, 24 Frank Lloyd Wright 
drive, Ann Arbor, MI 48105 (313) 662-3000 (AppleLink: 
V0218) 

The videotape of the session has been sent to Cupertino, 
where some of the Apple folks will have a chance to hear from 
MacHack developers first hand. 


Third party libraries 
Friday, the afternoon of the fifth day for twenty or so of these 
die hard programmers attendees were still hungry for more. 1 
was unable to attend concurrent sessions on CD/ROM Publish- 
ing and Doug Clapp'sMacBots Roundtable due to participation 
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in the libraries session. 

Jack Juni of Invention Software lead off the session by 
discussing some of the implementation decisions facing Macin- 
tosh library designers. He contrasted the Programmers Extender 
and MacExpress implementation and usage, explaining the 
Extender WData and EventStuff data structures to illustrate 
various points along the way. The WDatarecord is arelocate data 
structure whose handle is stored in the RefCon field of a window 
record. It contains fields for horizontal and vertical scroll bars, 
pictures, TextEdit records, list manager lists and other potential 
window contents. By using the information in the WData record 
the Extender library is able to completely process the majority of 
events, providing automatic dragging, resizing, scrolling, updat- 
ing, and editing of multiple windows. 

Juni also described mechanisms for allowing programmers to 
selectively turn off automatic event processing for specific 
windows, how the Extender's HandleEvent() routine reports 
back information to the program via the EventStuff record, and 
Extender Volume 2 support for custom list defProcs for lists of 
pictures, icons, and other types. He closed by contrasting the 
development time for software written with and without third 
party libraries, concluding that learning, development, debug- 
ging, and maintenance costs were all reduced by quality libraries 
and programming tools. 


Friday evening debriefing 

An informal conference debriefing took place for Friday 
evening for those who just had to get it out of their systems. 
Several suggestions for next years conference were made. 
Among the most interesting were; 

• Sessions shouldn't start earlier than 10:00 am. (Program- 
mers are night people!) Evening sessions should be added. 

* All sessions should be videotaped for later viewing or 
reference. 

More time needed between sessions, allowing for informal 
chats and session overrun 

e Special sessions for developers under non-disclosure for 
unannounced products 

* Improve support and representation from Apple and other 
vendors 

* Larger machine room, greater participation from women, 
handicapped and minorities 


Awards 

The group of twenty or so voted a set of informal awards, with 
the intention of making them a part of next years conference. The 
Vaporware award went to Full Write Professional (“Боп buy it, 
cause you can’t!”). 

The WordStar user interface award went to Microsoft Word 
3.0; (supply your own reasons). 

The Pinstripe award for sharpest threads went to Andrew 
Simms of MacTechnics, while The Kickback award for most 
casual dress went to both David Feldt and John Allegre, who both 
made sure formality at the conference was kept in check. 

The International award for coming the furthest went to 
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Johan Samuelson of Sweden, the Apple Basher award to Steve 
Jasik of MacNosy fame, and the Silver Plated Surfer award to 
Darin Adler and Lutus Langens. 

At 10 PM Jordan Mattson was still going strong, assigning a 
committee to prepare VAX based hardware proposals for the 
developers conferencing system and fielding questions from the 
final few. The beer was gone, it had been along week, and I was 
supposed to drive Jordan to the airport at approximately six the 
following morning so I wandered back to my house with a couple 
of other MacHackers who refused to letitend and we watched the 
video tape of the momings Apple Bash while working up some 
quick and dirty VAX/VMS configurations. Some things just 
refuse to die, and MacHack proved it was certainly one of them. 


MacHax best Hack awards 


What's a hackers' conference without a forum for good 
hacks? In the spirit of quick and dirty or simply fun little 
programs, The MacHax Group sponsored the First Annual 
MacHack Hack Contest. After hours of careful consideration, 
the following hacks were selected. All winners received the 
praise and adulation of untold multitudes of sentients. 

From Fritz Anderson came Heaplnit, an INIT and CDEV pair 
which permit you to resize your system heap. It comes complete 
with source code and all necessary documentation. Since he 
hijacked INIT 31, he also rewrote INIT 31 in C so Apple couldn't 
complain. Looking at the modification dates on his files, it was 
obvious that Fritz lost some serious sleep over this hack. This is 
a timely and useful contribution and should hit the networks for 
downloading asap. 

From Paul Snively comes SetPaths. Now, many of you have 
probably seen this one already. In case you haven't, SetPaths lets 
you specify your Poor Man's Search Path (PMSP). The PMSP 
is the set of directories your Mac looks through when asked to 
finda file without specifying a path name. Had Paul known about 
the contest beforehand, he would have certainly held back on its 
release till MacHack. So, to be fair, the MacHax folks permitted 
its entry. Now not everything has to go in the System folder! 

Darin Adler, Mitch Adler, Leonard Rosenthal, and Paul 
Snively created an interesting category with "The Best Hack 
Implemented in a Nonexistant Product." It's simply a small hack 
that speaks numbers. For example, Macintalk says 1004 as “опе, 
zero, Zero, four.” Aesthetics repugnant!. Theirhack instead says 
"one thousand four." It can handle numbers so absurdly large 
that it's quite humorous. They were planning to teach it to say 
really big numbers like 12443987598745987, 
345,983 ,498,234,897,234 as “twelve grillion and change...” 

Mother Nature and NASA won an overwhelming vote for 
power hack when television and newspapers reported they had 
jointly launched three missiles due to an unscheduled but highly 
effective lightning strike. 


Conference evaluations 


Most attendees heard about MacHack through MacTutor, 
MacTechnics (Ann Arbor’s 650 member Mac users group), or 
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through the grapevine. In this case the grapevine seemed to 
consist of equal parts telecommunications and word of mouth. 
There were many suggestions for possible improvments, but 
97% of those completing evaluations indicated their intention to 
return next year. See figure 2 below. 

Other trends which emerge from these evaluation responses 
indicate that one third of attendees would like more technical 
material, that the conference facilities would be acceptable for 
use again next year, and that more information on programming 
Mac IIs would be appropriate. Comments contained three 
recurring topics, scheduling conflicts between sessions, the need 
for alarger machine room, and better organization of moderators 
and equipment. 

In both conference content and opportunity to establish 
personal contacts with other programmers and developers Ma- 
cHack was a success, but the ideas and energy generated this time 
around should insure an even better conference next year. 
Abstracts should be submitted to Macintosh Technical Confer- 
ence (MacHack 88), ExpoTech, Inc., 1264 Bedford Rd., Grosse 
Pointe Park, MI 48230 no later than October 1st, 1987. For 
further information about next years event watch the pages of 
APDAlog and MacTutor, or call ExpoTech at (313) 882-1824. 
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Post conference evaluations - 36 responses 
Poor . | Fair X Good 


content 0% 81 73% 
facilities 0% 3% 418 
f ood 3$ 6% 67% 
technical level 34% 

Lisa Days 


how long а 
Mac programmer 


program Macs 


Mac SE Mac II 
machine used ; 21% 27% 


Fig. 2 Attendee Statistics 
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Mac Cad 


Benchmarks Re-visited 


With the emergence of the Mac 2 and the growing base of 
useful, easy to use scientific software, the field of desktop 
engineering will surely grow this year. The purpose of this article 
is to compare, from an engineering user point of view, the new 
Mac’s (using a Prodigy 4 as the equivalent of a Mac 2) with their 
counterparts in the IBM micro world, DEC mini world and IBM 
mainframe world. First the issue of compilation and linking will 
be addressed and then standardized benchmarks will be used to 
compare various machines from both a cost and performance 
point of view. Most of the non Mac results were provided to me 
by A. Tetewsky and D. Feenberg. These results will soon be 
published in Ref. 1. 


Compiling and Linking 


When using a compiled language for programming, such as 
FORTRAN, the issue of compile and link times is extremely 
important. In engineering applications, excessive compile and 
link times may make it worthwhile to develop engineering 
software in an interpretive language such as BASIC, and then 
port it to a compiled language after initial debugging апа 
algorithm development have been completed. If switching 
languages may not be practical, it may be worthwhile to stay in 
FORTRAN but develop the engineering software on a computer 
with faster compilation times. After program development the 
source code can easily be ported to the computer of interest for 
final compilation. 

Let's consider an example in finding complex roots of real 
polynomials. The 144 lines of program source code for this 
example can be found in Ref. 2. This example, like that of the 
Butterworth example in Ref. 3, uses single precision arithmetic 
butunlike the Butterworth example has virtually no input/output 
code. In this root finding example, a solution is found for a 30* 
order, well-behaved polynomial. The compile and link times for 
the 144 lines of code, using MS FORTRAN (both in the Apple 
and non Apple world), are indicated in Table 1 for a variety of 
micros. 


IBMAT Compaq386 MacPlus Prodigy 4 


60sec 20sec З sec « 1 sec 


Non Mac data from Sept 1987 Micro/Systems 
Table 1 - Compile and Link Times are Slow in the 
Non Apple World 


In this example, compilation and linking were done using a 
hard disk for the IBM AT and Compaq 386, while in the 
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Macintosh world, compilation and linking were done in RAM. In 
the IBM world, compiling in RAM is not significantly faster than 
compiling from the hard disk. This will always be the case since 
the operating system software, DOS, is written for 64k seg- 
mented 8086/8088 processors. Although an operating system 
which is developed for the 80386 or OS/2 should be better and 
improve compilation times, it will not be available for at least one 
year. If history is any guide, the wait time may be significantly 
longer. In addition, due to memory segmentation and the lack of 
a FORTRAN editor (a word processor must be used), it may be 
difficult to fit all necessary engineering tools into RAM. In the 
Macintosh world, memory is linear and easily expandable with 
third party upgrades. For example a 512K Mac can be upgraded 
to 2 Megs for about $500. This permits the creation of a 1.5 Meg 
recoverable RAM disk which is large enough to fit FORTRAN 
and many other useful tools into RAM. Therefore, compiling in 
RAM with a Mac is much faster than compiling from a hard disk. 

In addition, in the IBM world one must compile and link 
before the code can be executed. The user must nurse the 
computer through the compiling, linking and execution process. 
In the Macintosh world, linking is dynamic and therefore auto- 
matic from a user point of view. The user simply double clicks 
on "compile and execute" and the source code compiles, links 
and runs. 

The execution time for this complex root finding example for 
a variety of micros appears in Table 2. In this example all the 
micros with the exception of the Mac Plus had math coproces- 


CPU Clock 
Rate 


Execution 
Time 


Coprocessor 
Clock Rate 


7.8 MHz 
6 MHz 
16 MHz 
16 Mhz 


25 sec 
13.9 sec 
6.3 sec 
2.5 sec 


4 MHz 
8 Mhz (80287) 
16 Mhz 


*No Math Coprocessor 
Non Mac data from Sept 1987 Micro/Systems 
Table 2 - Execution Times for Complex Root Example 


The Table shows that, for this example, the Prodigy 4 is about 
10 times faster than a Mac Plus, more than 5 times faster than an 
IBM AT and 2.5 times faster than a Compaq 386. In the IBM 
world, with the exception of the PC, the math coprocessor never 
seems to run at the same clock rate as the CPU. That is why for 
this example, an AT and PC (where the math coprocessor is 
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matched to the CPU at 4.77 MHz) have similar execution times. 
The Compaq 386 is only twice as fast as the AT even though the 
Compaq has 32 bits rather than 16 bits and runs at 16 Mhz rather 
than 6 Mhz. In principal, when the IBM operating system 
software is written and a 16 MHz Intel 80387 math coprocessor 
becomes available, it should be in the same speed class as the 
Prodigy 4. Interestingly enough, the Compaq 386 is rated at 3.5 
MIPs while the Prodigy 4 is only rated at 2.0 MIPs. We can see 
that in numerical applications, MIP ratings may not tell the whole 
story (see Ref. 4 for example). 

Often the user may only be interested in the turn around time, 
which is the sum of the compile, link and execution times. For 
this example we сап see by comparing Tables 1 and 2 that the turn 
around times are significantly better in the Macintosh world. 
Table 3 summarizes the results for the complex root example. 


IBM AT Compaq 386 Mac Plus Prodigy 4 


73.9 sec 26.3 sec 28 sec 3.5 sec 
Non Mac data from Sept 1987 Micro/Systems 
Table 3 - Turn Around Times are Much Faster 


in Macintosh World 


The sample problem only had 144 lines of FORTRAN code. 
If we consider a “traveling salesman” program using 1500 lines 
of FORTRAN code, the comparison of compile and linking times 
are even more dramatic. Table 4 shows that the Macintosh and 
Prodigy 4 are considerably faster for larger programs than either 
the IBM AT or Compaq 386. 


IBM AT Compaq 386 Мас Plus Prodigy 4 


195 sec 65 sec" 19 sec 4 sec 


*Estimated based upon results of Ref. 1 
Table 4 - Larger Programs are Much Faster to 
Compile in Macintosh World 


Whetstone Benchmarking 


The Whetstone benchmark, devised in England by Curnow 
and Wichman in the Feb. 1976 issue of the Computer Journal, is 
an attempt to cover a typical mix of all floating point operations. 
This benchmark contains linear arrays, and add, subtract, multi- 
ply, divide and transcendental operations. Whetstones were 
originally written in ALGOL, but later translated to FORTRAN 
in 1979 by D. Frank. Since that time, many computer manufac- 
turers have rated their machines in terms of thousands of Whet- 
stones per second or kw/sec. Higher Whetstone ratings mean 
more powerful machines. Table 5 presents single and double 
Whetstone ratings for a variety of micro, mini and mainframe 
computers. In addition, ratios referenced to Prodigy 4 speed are 
indicated in the Table. A ratio of 1.7 means that the computer is 
1.7 times faster than the Prodigy 4. All computers, with the 
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exception of the Mac Plus, have math coprocessors or floating 
point accelerators. The poor double precision Whetstone rating 
of the Mac Plus may, relative to the IBM PC, may be one of the 
reasons there has been a scarcity of scientific software for the 
Mac. Ofcourse, we can see from this Table that the Prodigy 4 and 
hence new Mac 2 changes all that. 
Ratio Double 
Precision 
(kw/sec) 


Single Ratio 
Precision 


(kw/sec) 


Mac Plus* 42.8 
IBM PC 57.8 
IBM AT 98 
IBM RT** 200 
Compaq 386 241 
Prodigy 4 515 
MicroVAX 2 880 
VAX 11/780 1191 
VAX 11/785 1800 
VAX 8650 6100 
ІВМ 30840 5850 
ІВМ 3090 18000 


“Мо Math Coprocessor 

** Reference 5 

Non Mac data from Sept 1987 Micro/Systems 
Table 5 - Whetstones for a Variety of Machines 


The Whetstone results of Table 5 (with no I/O) can be 
compared to the Butterworth simulation results( with consider- 
able I/O and more representative of a realistic engineering 
application) of Ref. 3. Figure 1 shows that all the benchmarks, 
whether they be Whetstones or Butterworth simulations, yield 
about the same relative machine performance. Only the Mac Plus 
seems to yields results which are significantly benchmark de- 
pendent. It yields worse performance on the Whetstones because 
of it's lack of a math coprocessor. 


100 
Non Mac Data From Sept 1987 Micro/Systems 


10 


BUTTERWORTH 


SPEED 
PRODIGY 4 


SINGLE PRECISION 
WHETSTONES 


o 
2 
zi 
a. 
о 
< 
= 


PRODIGY 4 
VAX 785 
IBM 3084Q 


Figure 1 - Relative Machine Performance Is Ap- 
proximately Independent of Benchmark 
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The performance comparison of Fig. 1 can be placed into 
proper perspective when the cost of the host computer is consid- 
ered. For simplicity, computer cost can be considered to be the 
machines purchase price only. This neglects the cost of the small 
army of technicians required to operate the larger machines and 
the cost of software leasing agreements. We can see from Fig. 2 
that generally higher cost computers yield faster performance. 
However the cost is not always commensurate with the perform- 
ance. For example, a VAX 11/780 is only 1.5 times as fast as a 
Prodigy 4 and yet is 40 times more expensive. An IBM 3084Q 
is 11.7 times faster than a Prodigy 4 and is 500 times more 
expensive. On the micro side an IBM RT is 2.5 times slower than 
a Prodigy 4 and yet costs twice as much. 


DOUBLE PRECISION 
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Figure 2- Micros are More Cost Effec- 
tive Than Larger Machines 


If we normalize the computer performance 
as measured by double precision whetstones 
per second to the computer purchase price we 
can generate "bang for the buck" information. 
More "bang for the buck" means that the com- 
puter yields a higher double precision Whet- 
stone rating for less cost. Figure 3 presents this 
cost effectiveness information and shows that 
the Compaq 386, Prodigy 4 and Micro Vax 2 are 
very cost effective, with the Prodigy 4 yielding 
the most “bang for the buck". The curve also 
indicates that if a micro can do the job, itis more 
cost effective from a performance point of view 
than a mainframe. 


MAC PLUS 


Summary 

The intent of this article was to show that FORTRAN runs 
very efficiently on the Prodigy 4 (and hence Mac 2) when 
compared to non Apple micros. When compilation and linking 
times are taken into account, the comparison is even more 
dramatic. A relative performance curve is presented quantifying 
"bang for the buck" information fora variety of micros, minis and 
mainframes. As expected, the new Mac 2 appears to out- perform 
every other computer. 
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Stack Programming 


Hypercard's User Friendly Programming 


What Is Hypercard? 


Hypercard created by Bill Atkinson and friends will create a 
paradigm shift in the way we look at the Macintosh and informa- 
tion retrieval. What exactly is it? It isn’t exactly anything, it is a 
number of tools and concepts expertly moulded into a user 
friendly application generator and viewer. The closest way to 
think of it is, a cross between MacPaint, Guide and Smalltalk. It 
is best described as an object oriented authoring tool and infor- 
mation organiser. It is simple, fast and very powerful. 

In our modern age with the information explosion it is hard to 
keep track of data. Information stored in books, is often easier to 
access than that on a computer. With a book we can go to the 
index which gives us a link to a particular page, for example a 
chapter heading. The way we use reference books is usually non- 
linear. The term Hypermedia was coined in the late 60’s to refer 
to computer supported non-linear information media with mul- 
tiple paths between ideas. Hypercard is one of the most powerful 
forms of Hypermedia we have today. It’s applications vary from 
phone number databases to driving Laserdiscs. 


Hypercard Objects 


The main building blocks, or objects, of Hypercard are; 
Backgrounds, Cards, Fields and Buttons (Fig.2). A Hypercard 
application is known as a “Stack”. A Stack is made up of 
Hypercard objects. A Stack is made up of Hypercard objects and 
graphics (such as the book in Fig. 2). Each of these objects 
contains a Script. The Script language is called Hypertalk and is 
based on English and influenced by Pascal. 

When you launch Hypercard you first go to the Home Stack 
and the first Card is Called the Home Card (Fig. 1). The Home 
Card is important, no matter where you are in any Stack you can 
select the “Home” menu item under the “Go” heading and it will 
take you to the Home Card. You navigate through Cards and 
Stacks using the Browse tool, this is a cursor that looks like a hand 
(top right corner of Fig. 1). The icon like pictures in Fig. 1 are 
called Buttons. Buttons take you from Card to Card or perform 
a multitude of tasks. For example playing digitised sounds or 
advancing to the next frame on a Laserdisc. To go to the Calendar 
you Click on that Button. This is in contrast to the Finder where 
you double click an icon to go to an application. 

Hypercard appears superficialy as a simple program because 
most of its structure and functionality is hidden from the user. 
There are 5 user levels within Hypercard. The top most level, and 
easiest to use, is Browsing. This allows the user to navigate 
through Stacks and look at information but not to add or modify 
it. The next two levels Typing and Painting allow the user to add 
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Fig. 1 Home Card 


or modify written and graphic information. The last two levels 
are Authoring and Scripting. Authoring allows use of the Field 
and Button tools and Power Keys (short Cuts). The Scripting 
level allows full use of the Hypercard programming language 
called Hypertalk, and the use of instant commands called “Blind 
Typing”. [Note that Hypercard offers a protection mechanism 
forstacks that allows programmers protection via a menu item. 
This prevents scripts from being read.] 


Ld 


é File Edit Go Tools Objects 


Secret Diary (2) 


Pessword 


8/23/87 s 


This is where you can write your 
Ihis із where ` secrets because they ere 
i password protected. 


Shopping vith Susi. For Exemple 


Met JPC for Lunch: Talked about | 
the new deal. i 


Suprise party Guest tist: 
Peter Robinson 


Nic Fyfield 
Peter Mountford 


Background Field 


Scrolling Field 
Card 


Background Graphic Button 


Fig. 2 Hypercard Elements 


© The Essential MacTutor, Vol. 3 


Ld 


é File Edit Go Tools Objects L 


ера 
Р Ll 


Е %% 5% 522 


Fig. 3 Hypercard Tools 
Tools of the Trade 


Hypercard has a number of tools to help in the development 
and customization of Stacks. There are Paint Tools (Fig. 3) that 
work much like MacPaint but with many more powerful features. 
One of these features is that you can use these tools directly from 
Hypertalk. 

The Tools and Patterns are on “Tear Off" menu's. You simply 
drag the cursor to the bottom or sides and the menu's tear off, then 
they act as windows. As well as the paint features in the tools 
menu you can select a Button tool , and a Field tool , as well as 
the Browse tool. The Button tool (next to the Browse tool Fig. 3) 
lets you manipulate Buttons (cut, copy, paste, resize, etc.). By 
double clicking a button you can assign or change attributes (Fig. 
4) and enter the Script Editor (Fig.5). Entering the Script editor 
directly is possible by double clicking the Button while holding 
down the shift key. The Field tool does basically the same thing 
except for Fields. One difference is that with Buttons you can add 
an Icon and link it automaticaly to another card, and with Fields 
you can change font attributes. 

The Message box which is a long rectangular text entry 
window (Fig. 3) is a powerful tool. It is used to give Commands 
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Fig. 4 Button Info 


© The Essential MacTutor, Vol. 3 


and get Functions (like an instant window). For example you can 
type in “go to next card" then press enter or return and the action 
will take place immediately. This is very useful to test script 
ideas. When the user sets preferences to “Blind Typing”, he can 
type into a hidden Message Box. This allows instant Hypertalk 
access directly from the keyboard at any time. 

The Script Editor allows you to enter and modify Scripts. It 
automaticaly does the formattng for you. The window is 
scrollable vertically but of fixed size horizontally. Sometimes 
script lines can be longer than the window, this is allowable, you 
just won't see the rest of the line. Or you can put in a “soft” return 
by typing in an option-return, which allows visual splitting of 
lines but still retaining the line integrity. This is displayed by an 
— special character. You can cut, copy and paste from and to 
scripts using the editor but only with command keys (command- 
c, etc.). The reason for this is that the editor is really a dialog box. 
You can also search using command-F. Printing of scripts is 
possible from the editor or from Hypertalk itself. 
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Script of bkgnd button id 21 = "Password" 


рп mouseUp 
global passed --Set as a global so it can be used everywhere 
repeot forever 


beep 

ask password "Set New Password” 
if it is empty then exit mouseup 
put it into passed! 


beep 

ask password “Please Confirm Your Password” 
if it is empty then exit mouseup 

put it into passuwd2 

if passed! = passed2 then exit repeat 


end repeat 
put passwd2 into passed 
“Your Password has been Confirmed” 


Fig. 5 Script Editor 


Behind the Scenes 


Let us begin by looking at a few basic concepts of Hypertalk. 
Hypertalk is built around a system that sends messages to objects. 
A message is basically a command or function. The Hypercard 
application sends messages about the current state of the Macin- 
tosh and Hypercard to objects, each object responds to messages 
depending on its script. Hypercard has an object message hierar- 
chy as shown in Fig. 6. For example if the mouse is pressed, 
Hypercard sends оша message “mouseDown” . If the tool cursor 
is on a Button, a ^mouseDown is sent to that Button, if there is no 
Button or textField under the tool the message is passed on to the 
Card. This message travels up the hierarchy until it reaches a 
level with a script begining with “on mouseDown”. 

It then executes the instructions following “on mouseDown 
“until itreaches “on end mouseDown" at the end of the script. If 
there is no recipient of the message as it passes up the hierarchy 
it simply vanishes at the top. Messages are passed from Buttons 
and Fields etc. through the hierarchy up to the Hypercard 
application. 
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Fig. 6 Message Hierarchy 


When Hypercard seems to be doing nothing it is passing 
messages down the hierarchy. For example if nothing is happen- 
ing it sends a message "Idle" to the Home Stack which passes it 
to the current Stack in turn passes it to the Background which 
passes it to the Card which passes it to the Buttons and Fields. 

Normal programs are self contained, that is they have a 
"begin" and an “end”. Hypercard on the other hand has individual 
parts of a program within the objects it relates to. This has the 
advantage of being modular. Forexample, if you like the function 
of a button that puts a time and date stamp in a selected field, you 
can easily copy and paste that button into any stack. 

Hypercard also has some limitations, you are limited to the 
size of a normal Macintosh screen, no color, and you can view 
only one card at a time. Some of these limitations have already 
been addressed, such as the introduction of scrolling fields which 
aid the size limitation. 


The Secret Diary 


I have written a short example Stack Called Secret Diary. I 
will use itto demonstrate the format and Ideas behind scripts. Let 
me fist describe what the Stack does. When you open it you are 
confronted with the same Card as in Fig. 7. When you press 
Button "Push to Start" up comes an alert box warning you to 
remember your password, then up comes a dialog box asking you 
to enter a password (Fig.8). A second dialog box pops up asking 
you to confirm your password, then an alert telling you your 
password has been confirmed. When you press “Close Help" you 
are presented with a card like Fig. 3. There are two fields where 
you can enter information. Pressing the key Button on Fig. 3 
brings up a dialog box (Fig.8) asking you to enter your password. 
When you have entered your password correctly the Secret Diary 
Field is presented (Fig.2), allowing you to enter information you 
want to keep from prying eyes. This field can have as much 
information as you like, simply by scrolling. You can now press 
the Hide Button to hide the Secret Diary or the Password Button 
to change your password. 

New pages can be added by pressing Button "New Page", 
when they are created the current date is put into the field on the 
top of the page. The left and right arrow Buttons move you to the 
previous and the next cards respectively. The icon Button with 


736 


the 3 cards shows all the cards in the Stack. The Home icon 
Button takes you to the Home Card, and the question mark takes 
you to the Help screen (Fig.7). 


What's in a Script? 


A script that reacts to a message is called a Message Handler. 
А script may contain many handlers. For example the Secret 
Diary Stack Script has an on openStack handler containing an 
instruction to close the Message box, hide message box, and an 
end of handler end openStack. It also contains a handler closeS- 
tack, which makes sure the Secret Diary is closed on exit. 

Scripts can be very simple such as in Fig. 7, where all the the 
Buttons have mouseUp handlers. These Buttons (except “Push to 
Start" and "Close Help" ) are background Buttons because I 
wanted them to appear on all cards. The Buttons “Push to Start” 
and “Close Help" are Card Buttons and I designed them to appear 
on the first card only. The Home button simply has a handler and 
“go home”. Menu objects can be “Called” by using the command 
doMenu with the name of the menu item as a parameter like in 
Button “New page”. This is typical of the simplicity of Hyper- 
card. The right angled arrow is a return arrow it allows you to go 
back to the card from which you came into the stack from. If you 
look at Listing 1 of the Stack script you will notice an instruction 
that says “push recent card” this stores the address of the recent 
card on the “real stack”. The return Arrow Button tells Hypercard 
to pop card (from the “гез! stack") so Hypercard jumps to that 
address. This is a good example of the modularity and flexibility 
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article for MacTutor. Hypercard: A New 
Gener ation of User Friendly Programming. 


Help 


Chick on the Key to open Secret Diary. 
Click on Password to change it at any time. 
Click on Hide to hide your Secret side. 


This Stackware can be used free of charge 
as long as it is not used for commercial 
purposes without permission. 
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normal activities. The right side is your 
password protected side. 


Close Help 


Click on this icon to show all cards. 


Written by Fred Steuder 
Ecofin Research and Consulting 
Zurich Switzerland © Aug 1987. 


Go Home Add a New Page Prev Page 


4 


on mouseUp 

Өз moweep show all cards 

go home 
end mouseUp end mouseUp 

on mouseUp 

on mouseUp --a closing iris effect 

doMenu "new card" visual effect iris close 
end mouseUp --go to the card 

--Where you came in from 

on mouseUp pop card 


--opening from center out end mouseUp 


visual barn door open 
go to prev card 
end mouseUp 


Fig. 7 Secret Stack 


on mouseUp 
--closing from outer edge 
visual barn door close 
go to next card 

end mouseUp 
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of Hypertalk. The entry point to the Stack is the Stack itself. We 
only want to go back to the card we came from sometimes, so it 
wouldn't make much sense to put “рор card" under the handler 
closeStack, because we may want to go to the Home Card or 
somewhere else. 

How was it done? First I created a new Stack, then copied the 
graphic of the book into the Background (type command-B to get 
in and out of background mode). Then I created the Fields (Fig. 
3), with attributes show lines and opaque. The left field is called 
"Notes" the right is called “Blank” and the Date field “Date”. The 
help screen is a picture that I created with the paint tools. If you 
look at the Script for the Help Button it first locks the screen so 
the user is not aware that the changes don’t occur simultaneously. 
Then it toggles the visable attribute of the fields Note, Blank, and 
Date. It also puts up the Button “Close Help” (Fig. 7). This is a 
very useful feature because you can have as many hidden fields 
as you like that pop up. 

Variables are declared by simply refering to them. For ex- 
ample in Listing 4 the line put it into passwd1. Hypertalk uses 
it as a temporary variable. The script puts up a text entry dialog 
with ask password *Set New Password". The parameter pass- 
word after ask translates the enterd text into an encoded numeric 
form (what this is for will become apparent later). A suffix after 
the ask “name” statement is with “name of button" or “name 
of another button". Up to 3 buttons can be added. The text entry 
is put into the temp variable it. An alert is of the same type except 
insted of ask itis answer. Now back to the instruction put it into 
passwdl, Hypertalk checks to see if the word passwd is a 
reserved word if not then it becomes a variable. To make a 
variable global, the statement global is put in front of the variable 
name, it has to be declared global in each handler it is used in. 
Variables are lost after quitting Hypercard. To store my password 
I put it into a hidden Background field called “pass”, on open- 
Stack I put background field “pass” into the variable Passwd. 
Look at listing 1 and compare how similar to the last sentence it 
is. It is almost English. Since the Password has to be stored it is 
useful to encrypt it using the parameter password after the ask 
statement. 

Each Button or Field on acard is suspended in it’s own layer. 
This means that I can create a large invisible Button (“Big 
Button”) such as I have done in the opening of the stack, that 
covers the whole card. It is placed on top of all the buttons and 
fields. It doesn’t contain any handlers so it doesn’t do anything. 
I have put the button “Push to start" on top of it. This means that 
the user can only press the Button “Push to Start” all the other 
buttons are obscured by “Big Button”. This helps you control the 
sequence a user can choose. If you look at Listing 3, the Button 
"Big Button” is hidden after the user enters his password. Now 
the other buttons work normally. You can control where a button 
is in a layer by using the menu commands “Send Farther” or 
"Bring closer". The same principles also apply for fields. 

The Hypertalk control structures such as "If", “Then”, “Else” are 
quite standard such as “if the mouse is down then Beep”. With 
repeat loops such as in Listing 4 you exit either the repeat by the 
statement "exit repeat" or exit the handler eg. “exit mouseUp”. 
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Fig. 8 Password 


To finish off this section on scripting I want to once again re- 
inforce the concept and power of Messages. Look the Handler 
closeStack in Listing 1, the entire script can be replaced with a 
one line Message; send mouseUp to bkgnd button hide. 

External procedures can be added to stacks very simply. They 
are in the form of command (XCMD) and function (XFCN) code 
resources. They can be added to stacks using ResEdit or any other 
resource moving tool. When a command in a script cannot be 
found, Hypercard looks for the resources of type XCMD and 
XFCN with the same name as the unknown command, therefore 
you can call external code by using handlers to the named 
resource. 

Hypertalk is a powerful user friendly language that will 
generate many new vistas in the Mac environment. There will be 
a big influx of Stackware on the market. Soon the Hypercard 
installed base will be very large because Apple is bundling it with 
every new Mac and offering it as an upgrade at nominal cost. 
Happy Hypercarding. 


Where to get more information? 


• "The Complete Hypercard Handbook" 
by Danny Goodman (Bantam Books) 


* "Hypercard Power: Techniques and Scripts" 
by Carol Kaehler 


* "Hypercard Script Language Guide" by Apple, available 
from APDA. 

Fred Stauder is a developer with Ecofin Research and Con- 
sulting Ltd. who specialise in consulting to the Swiss Banks and 
Financial Institutions. They are Registered Apple Developers 
and a Dynamic International company. 


Listing 1 
stack 
on openStack 
-set global variable passwd 
-for storage of encrypted Password 
global passwd 
put bkgnd field "pass^ into passwd 
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push recent card 


hide message box Listing 7 
end openStack Key 
on mouseUp 


on closestack 
-neke sure that the Secret Diary is Closed on Exit 
set lockscreen to true 
-to make the events appear simultaneous 
show bkgnd button “hide” 
click at the loc of bkgnd button “hide” 
-instead of re-writing the script we can click it 
hide bkgnd button “hide” 
set lockscreen to false 
end closestack 


global passwd 
-Set as а global so it can be used everywhere 
repeat forever 
beep 
— Ask puts up text enty Dialog Box. 
- the word Password is used to encrypt the entered 
-text into а number format 
ask password "Please enter your Password’ 
-Puts up text enty Dialog Box 
-it compares the global passwd 
-to the result of the enterd text 


Listing 2 if passwd = it then exit repeat 
background beep 
on newcard -Ànswer puts up а dialog box with up to 3 buttons 


-Тһе current date is added to a new card 
put the date into bkgnd field “date” 


answer "Your Password is Incorrect^4 
with "Bye" or "Try Again" 


end newcard if it is “Bye” then exit mouseup 
end repeat 
Listin -Shows the Secret diary and enables 
Push to start - the Password and Hide buttons 
on mouseUp set visible of bkgnd field "secret^ to true 


answer “Do not forget your Password” -Alert 
set lockscreen to true -hide events from user 


show bkgnd button “hide” 
show bkgnd button “Password” 


show bkgnd button “Password” end mouseUp 
show bkgnd button “Hide” 
-Big button covers 811 the other buttons Listing 8 
-except Push to start. help 
-There is no script in Big Button so it prevents on mouseUp 


—811 the other buttons from being pressed. 
-This helps control the sequence а user can choose 
hide button “big button” 
click at the loc of bkgnd button “Password” 
-Do the script in button Password 
put the date into bkgnd field “date” 
hide button “Push to start’ 
-used to toggle the buttons off 
hide bkgnd button “Password” 
hide bkgnd button “Hide” 


set lockscreen to true 

set visible of bkgnd field "Notes^-^ 

to not the visible of bkgnd field “Notes” 

set visible of bkgnd field "blenk^*4 

to not the visible of bkgnd field “blank” 

set visible of bkgnd field "Date"4 

to not the visible of bkgnd field “date” 

set visible of bkgnd button “close һе1р”- 

to not the visible of bkgnd button “close help” 
set lockscreen to false 


set lockscreen to false end mouseUp 
end mouseUp i 
| Listing 9 New Page 
close help on mouseUp 
password on mouseUp doMenu "New Card" 
on mouseUp click at the loc of bkgnd button “Help” | eng mouseUp 
global passwd -8 Simple way of “doing” a button 
-declare passwd as а global end mouseUp Listing 14 
-(availeble in 811 places where it is declared) Show all 
repeat forever on mouseUp 
beep Prev show 811 cards 
ask password “Set New Password” on mouseUp end mous 
if it is empty then exit mouseup visual barn door open 
put it into passwdi -opening from the center out Listing 15 
beep go to prev сага Hone 
ask password "Please Conf irm Your Pessword" end mouseUp on mouseUp 
if it is empty then exit mouseup go home 
put it into passwd2 | end mouseUp 
if passwd! = passwd2 then exit repeat Next 
end repeat оп mouseUp 


put passwd2 into passwd 
put passwd into bkgnd field “pass” 


visual barn door close 
-closing from the outer edge to the center 


answer "Your Password has been Confirmed” go to next card 
end mouseUp end mouseUp 

hide return 

on mouseUp on mouseUp 


hide bkgnd field “secret” visual effect iris close -а closing iris effect 

hide bkgnd button “hide” pop card - go to the card where you came in from wr 

hide bkgnd button “Password” end mouseUp зей 
end mouseUp SEEDS 
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The Visiting Developer 


Help Documentation System Review 


The Importance of Documentation 

I believe that the secret of the Macintosh revolution is based 
mainly of two things: an easy to learn, nonthreatening, graphics 
based interface, and consistency in applying that interface to each 
new Macintosh application. The one missing component—auntil 
now, that is—has been a way to create consistent on-line docu- 
mentation. 

Why didn't Apple Computer provide documentation proce- 
dures as part of its otherwise excellent operating system? A 
source at Apple said that originally they thought that the Macin- 
tosh concept was so good that it would not require documenta- 
tion. He also confessed that they are no longer that sure. The 
result is that—until now—the Macintosh lacked consistency in 
on-line documentation. Some software houses who do provide 
on-line documentation, are not consistent across their product 
line. 

Indeed, it would seem a contradiction that easy to use, 
intuitive programs should require on-line documentation. The 
real the purpose of documentation is not limited to illustrating the 
common, intuitive and easy to use interface of Macintosh pro- 
grams. Complete documentation covers a wide spectrum: the 
machine itself, its operating system, the application program, and 
how the program is used within the user's organization. No 
single entity that has the capacity, the knowledge or the resources 
to produce complete documentation. Complete documentation 
is an incremental collection of information contained in hard- 
ware manuals, operating system manuals, application manuals 
and tutorials, corporate standard instruction manuals, corporate 
training programs, memos and other instructions. Documenta- 
tion is used in many different ways: the developer has different 
needs than the user; the novice has different requirements than 
the power user; the new employee differs from his supervisor; 
production does things differently than the accounting or adver- 
tising departments. 

To fill this wider scope, documentation must be modular: the 
information provided by the prime source must be editable at 
each new level of use to adapt it to that level’s needs. Considered 
in this new light, documentation becomes a useful and integral 
component of your product and of the whole Macintosh environ- 
ment. Now documentation helps to transmit new and useful 
information at each level of use. Documentation changes from 
a costly add-on to a hot, new, useful and salable feature. 

Toachieve modularity, documentation needs a standard tool, 
available to all Macintosh developers and users. HDS, an off the 
shelf component, is similar in concept to the tool box in ROM. 
HDS provides consistency in documentation in the same way 
that Apple's tool box provides consistency for the other parts of 
the Macintosh user interface. With consistent documentation, 
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Fig. 1 The Help On-line Documentation System 
you Save time, you save money and you produce a better and 
more useful product. 
What Is HDS 

HDS is a two part system: The Help Editor desk accessory 
creates the on-line documentation, and the Help desk accessory 
(the run-time) lets the end user access this documentation. Since 
Help is a desk accessory, it is independent of—and transparent 
to—the program that it documents. (See figure 1, the Help Editor 
Menu. ) 

The independence of the Help Documentation System makes 
it an ideal documentation tool for Macintosh applications and it 
can be used at every stage in the development and usage of a 
Macintosh program. A new layer of documentation can be added 
at each stage: 

е Apple Computer can document the Macintosh hardware 
and the Systems software 

е The developer can document the features of his application 
program 

* The VAR can document the components added to the 
system 

* The MIS manager can document how the package is used 
within his corporation 

* The departmental manager can document how the package 
is used within the department 

e The user can document how he goes about doing specific 
tasks 


A new subset of the documentation can be created for specific 

purposes: 

* A basic set with tutorials can be created for training new 
workers 

е Ап advanced set documenting shortcuts сап be created for 
power users 
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• А foreign set can be created for overseas offices 


This is the first time that the basic documentation produced by 
the developer can be expanded, modified and made useful at 
every stage in the usage of a Macintosh application program. The 
Help Documentation System is an important step in the direction 
of creating customizable software. 

Why on-line? First, very few computer users manage to keep 
the manual within handy reach. Second, when you release a new 
version of an application, you can easily revise the documenta- 
tion to match, without the time and expense of printing a new hard 
copy user's guide. The trend is catching on, notice the prolifera- 
tion of Read-me-First documents being distributed with Macin- 
tosh programs. With the advent of hard disks and CD ROMs, on- 
line documentation is becoming the rule rather than the excep- 
tion. 

Who Is the HDS Package For? 

HDS takes a lot of the work out of software documentation. 
It is self evident that consistency across applications is a mayor 
benefit for Macintosh users. The same benefit is realized by the 
consistency in documentation provided by HDS. Developers can 
rid themselves of a giant headache with HDS, leaving more time 
for code development. 

With a few instructions, your program can call the Help desk 
accessory to provide context sensitive help and extended alert 
messages. Corporate Trainers and VARs can also make use of the 
HDS system for creating customized on-line instruction and 
training materials. 

HDS provides the unprecedented opportunity to replace how 
to books with on-line manuals. The best place for help is right on 
the screen in front of the user. If this help is interactive with the 
program being used, so much the better. HDS provides both of 
these desired features. With the advent of CD ROM the space 
problem will be solved and on-line manuals will come into their 
own. 

Some international companies translate the language inter- 
face for their software; others don’t. In providing software 
packages for the international market, it’s often better to leave 
key words and phrases in English and to provide explanations in 
the user’s native language. Since Help files have their own font 
(Cyrillic, Katakana, and so forth), the program interface can be 
written in English, and the documentation, in any other language. 

Most people make notes and reminders to themselves. The 
most accessible place for these notes is with the rest of the 
information about the program you are using. 

Design Criteria for HDS 

The following criteria were agreed upon in the design of the 

Help Documentation System: 

• HDS requires a well known and workable metaphor. 

¢ HDS must follow the Macintosh user interface guidelines. 

* The documentation for any program might be very large. 

e Access must be quick, therefore, the path to any information 
must be short. 


As aresult, we selected the “well referenced book" metaphor 
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22 Table of Contents 


ГЕ Subtopics | 
Bibliography 


Checking Errors 
Checking Programs 
Debugging 

Editing Programs 


Q 


Fig. 2 The Table of Contents 


and implemented equivalents for: 
e Table of Contents 
e Alphabetic Index 
e Glossary 
e Cross Referencing 
e Visual Glossary 
e List of Illustrations 
e How to Use This Book 


Then we extended the metaphor with concepts from the 
Macintosh User Interface Guidelines and Macintosh usage: 

e Help for Menus 

e Context Sensitive Help 

e Extended Alerts 


The access path to the documentation is through a multibran- 
ched, three level tree. The root node has 7 branches which 
correspond to the implementation of the “well referenced book” 
metaphor and its extensions. These 7 branches correspond to the 
seven access points to the documentation. 

Organizing your Documentation with HDS 

There is an intrinsic structure imposed on your documenta- 
tion by (ће “well referenced book" metaphor of HDS. Within this 
overall organization, you are free to create the structure that is 
most convenient for your documentation. 

HDS documentation has two principal purposes or modes: 
The didactic mode, for teaching, is created and accessed with the 
Contents feature. The reference mode, for fast random access, 
uses all the other access features. (See figure 2, Table of Con- 
tents) 

Table of Contents 

The didactic part of your on-line documentation will be 
similar in organization to a textbook. The Table of Contents 
feature will help you organize your on-line documentation by 
Topics and Subtopics. A Topic is a like a chapter in the book. 
You may create any number of Topics and up to 31 Subtopics per 
Topic. Within this limitation of 31 Subtopics per Topic, you are 
free to choose the organization that you deem best for the project 
at hand. (See figure 3, Aplhabetic Index) 

The Index is a most powerful organizing feature of HDS for 
it allows you to create a glossary and references to any message 
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in your documentation. While the table of contents leads the user 
in a sequential manner, the Index allow fast random access. 
While the novice user is more likely to use the table of contents 
to navigate the documentation, the experienced user and the 
power user are more likely to use the index to find specific bits 
of information. The index must satisfy the novice and the power 
user. 

The organization of the Index is hierarchical. The Index 
displays the list of Key Words in alphabetic (ASCII) order. You 
select a Key Word and then you are given a second multiple 
choice: Major Reference and General Reference. (See figure 4, 
Major Reference) 

Major Reference 

If there is a whole Topic or Subtopic dedicated to a Key Word, 

then the reference to that Topic or Subtopic is called a Major 


Riphabetic Index 
re 


O New Key Word 


Fig. 3 Alphabetic Index 
Reference. Visually, the method of access to a Major Reference 
is similar to the method of access to a Topic from the Table of 
Contents. This similarity creates an intuitive image of the 
importance of the reference. 

You can create any number of references to any part of any 
message within your on-line documentation. These General 
References are shown in alphabetic (ASCII) order for each Key 
Word. Visually, the access to General References is different 
from the access to Major References in order to create an intuitive 
image of their relative importance and usage. 


Main Reference for Key Шога: 
3,  tdit 


How To 
Enample 
Statistics 
Tips 

Short Cuts 


Bilbliography 
Checking Errors 


Checking Program 
Controls 
Debugging 

"Editing Programs 
Labels 


Fig. 4 Major Reference System 
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The Index feature allows you not only to create references to 
any part of the documentation, but it lets you write one or more 
messages for each Key Word. If you write a ‘Definition’ for each 
key word, then, the sum of these ‘Definitions’ constitutes your 
on-line glossary. 

Cross References 

The cross referencing feature is a powerful organizational 
aide for the author. Cross References are selected Key Words in 
Help messages that have been specifically outlined by the author 
to induce the reader to obtain additional information about the 
subject he is perusing. This feature permits you to include a 
certain amount of intelligence in the documentation, for ex- 
ample, іп a passage about ‘Cut’, you might add the phrase: “See 
also, Paste’. 

The outlined Key Word points to the Key Word’s list of 
references and messages. From this list the user selects the area 
of interest. 

Visual Glossary 

A visual glossary is a new type of book that only contains 
pictures with legends. A visual glossary is used to find the 
unknown names of familiar objects. 

HDS has a Help Scrapbook where you may paste the icons, 
pictures or other graphic elements used by your application 
program. The user can browse through the Help Scrapbook to 
find information about things (doodads, icons, whatchamacal- 
lits, et al.) whose name he does not know, or has forgotten. It is 
often enough to add legends to the picture to describe it. If you 
need to give more information than would comfortably fit in a 
few legends, you may create a message associated with the 
picture. 

List of Illustrations 

The Help Scrapbook has an alphabetically ordered Catalog 
that acts like a list of illustrations in a book. If the user knows the 
name of the thing that he is looking for, he can find it faster by 
using this Catalog, instead of browsing through the Help Scrap- 
book. 

Help for Menus 

The most intuitive way to obtain help for a menu command is 
to follow the same procedure used to execute the menu com- 
mands, in other words: to execute a menu command, select it with 
the arrow pointer; to get help for a menu command, select it with 
the “2” pointer 

To implement this feature, the Help and Help Editor desk 
accessories capture the application's menu bar. When you select 
any of the application's menu commands with the “?” pointer 
while the HDS accessories are active, you open a message for the 
command, instead of executing the command. 

For the Menu Help feature to function properly with your 
program, it is absolutely essential that you follow Apple's 
guidelines with respect to the programming and operation of 
your menus. Should there be any problems with the interaction 
between HDS and your menus, please contact Help Software's 
technical staff. (See figure 5, below: Context Sensitive Help) 

Context Sensitive Help 

On-line context sensitive help is an implementation of 

Apple's guidelines of giving the user extra help without referring 
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him to external documentation. By the very nature of context 
sensitive help, it must be initiated from within the program. We 
suggest that you implement context sensitive help in two steps: 
(1) When the user hits 'Command-?' , convert the pointer to a “?”. 
(2) When the user selects anything on the desk top with the “?” 
pointer: an icon, a menu item, ora field in a document, make your 
program call the Help desk accessory and passes it a parameter 
that indicates which message should be displayed. (See figure 7, 
Extended Alerts) 
Extended Alerts 

“Under no circumstances should an alert message refer the 
user to external documentation for further clarification. It should 
provide an adequate description of the information needed by the 
user to take appropriate action.” From The Macintosh User 
Interface Guidelines, Inside Macintosh, Page 1-69. 

Yourapplication program can call the Help desk accessory to 
display a message that will not fit into an alert box. We suggest 


$6-? 


Help In Context Messages 


Division by Zero Error 
File - Меш 

File - Open... 

File - Close 

File - Save 

Illegal Operation Error 
Unable to Undo Error 


that you give the user the choice to either see the Extended Alert 
message or return to the application by adding a Help button to 
your alert boxes. 

Help in Context and Extended Alerts are identical from a 
programming point of view, the only difference is the user's 
perception of their functionality. You may create up to 65535 
messages of this type and use them either as Help in Context 
messages or as Extended Alerts. 

Good technical books have a section on how to use them. The 
About Help message can be edited. Thus, you can alter it to 
include such instructions as how you implemented the Help In 
Context, or your Extended Alert procedures. It also means that 
you can translate the About Help message into any language, in 
the event you export your program. 

Book Mark 

HDS provides the user with several bookmarks to keep track 
of his place in the documentation: (1) The Topic and Subtopic 
last read have check marks next to them. (2) The Help Scrapbook 
opensat the last place it was used. (3) The Key Word last selected 
in the Alphabetic Index is highlighted. (4) For the last Key Word 
used, the General Reference last selected is highlighted or the 
Subtopic read as a Main Reference has a check mark next to it. 

Slide Show 
Some messages are easier to understand if shown screen by 


742 


screen; we call this feature Slide Show. Others messages are 
easier toread line by line (standard scroll). The Help Editor menu 
allows you to select the best type of scroll for each message. 
The HDS uses a “?” pointer to indicate clearly that the 
Macintosh is currently in the Help mode of operation. 


Help Font 


This feature is aimed at the international market. There is no 
Help font as such. HDS uses the font installed in the on-line 
documentation file's resource fork. 

А pop up menu in the Open File box allows you to select the 
font you wish to install in the Help file that you are creating. 

This means that a program interface written in English can 
be documented in any language and font. The reasons for storing 
afontin the resource fork of the HDS on-line documentation file 
are: (1) This font will not interfere with your application's font 
menu. (2) If a user needs help, things should be as easy as 
possible. You do not have to worry whether the proper font is 
installed in the System file. Since each HDS on-line documen- 
tation file carries its own font, you can provide documentation for 
the same application in several languages. 

Some software companies can afford to translate their pro- 
grams into several languages, though most cannot. Therefore, in 
foreign lands, some programs operate in the native language, and 
others operate in English. This means that the foreign user must 
continually make a mental jump from ‘File’ to ‘Archivo’, and 
from ‘Open’ to ‘Abrir’. This is the opposite of consistency. 
Foreign technical words find their way into everyday language. 
In Latin America, terms such as Strike, Out, Foul and Fair are 
frequently used when talking baseball; these people don’t speak 
English, and yet everyone understands. In a similar manner, 
English technical terms are common in software packages writ- 
ten for the international market. It is often better to leave the user 
interface in English, and to give the explanations in the native 
language. 

Many good reasons assist Apple Computer in promoting the 
‘Localizing’ of Macintosh software. HDS offers an alternative 
solution that might be more adequate in some situations. 

Invoking Help 

There are three ways in which users can activate the Help desk 
accessory: (1) From the Apple Menu, (2) using ‘Command-?’ 
if you have implemented Help In Context and, (3) pressing the 
Help button in an alert box if you have implemented Extended 
Alerts. 

An application program may be documented with HDS 
without implementing the Help In Context and Extended Alert 
features. This is the road that a user would take to document a 
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program for which he does not have access to the source code. It 
is worth while for developers to implement these features in their 
programs, since the small overhead of extra code is more that 
Offset by the advantages gained in user friendliness provided by 
these two features. 
Access Path 

Once the Help desk accessory has been invoked by any of the 
three methods shown above, the user has access to the on-line 
documentation in several ways. This information is never more 
than three operations away. 


Sample Code to call Help from your program 


/* Sanple code for Help In Context x/ 
/* and Extended Alert calls to the x/ 
/* Help Desk Accessory using Aztec C x/ 
/* Include the bold faced code in x/ 


/* your program */ 


/* Desk manager library */ 
*include Cdesk.h) 


/* Parameter block library */ 
*include (pb.h) 


/* Global variables to test for */ 

/* the Help desk accessory */ 

/* Help is the desk accessory refnum x/ 
short Help=0; 


/* inContext is the message to be %/ 
/* displayed */ 

long inContext; 

nainC) 

doneflag- FALSE; 


/* peremeter block to call Help */ 
PeramBlkRec parem; 


/* Main program loop*/ 
while C!donef lag) 


SystemTask( 2; 
/* If Help<@ then the Help desk */ 
/* accessory is open*/ 


/* If Help-WindowKind  */ 
/* of the active window then*/ 
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/* the Help desk accessory is active 


If CHelp<@ && Help==CCWindowPeek )FrontwWindow()) 


->»windowK ind) 


/* Assign the parameter block 
/* values for а desk accessory 
/* control call */ 

param. ioComp let ion=NULL ; 


/* accessory refnum assigned by 
/* the OpenDesk Acc call */ 
param.u.cp.csRefNum-Help; 


/* 5000 is the csCode for the 
/* InContext feature */ 
param .u.cp.csCodez5000; 


/* inContext is the message */ 

/* to be displayed */ 

*(Clong*)&Cparaem.u.cp. 
csParam))=inContext; 


/* it’s an asynchronous call */ 
PBControlC&parem, TRUE); 


/* Reset Help x/ 
Не1р-0; 
) 


temp - GetNextEventCeveryEvent, 
&myEvent); 
switchCmyEvent . what) 


x 
x 
x 


/* To call the Help desk accessory 
/* from a routine in your program, 


/* insert the following code*/ 
x 


x 
x 


/* Open the Help desk accessory */ 
/* *\P” is a PASCAL String in Aztec C 
/* *\0” is NULL */ 


/* Help In Context or Extended Alert 
He 1lp=OpenDeskAcc(“\P\OHelp”); 


/* message to be displayed */ 
inContex t=num ; 
x 


x 
x 


*/ 


*/ 
*/ 


*/ 


х/ 


*/ 
*/ 


"I 


*/ 
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Conference Reports 
MacHack West, Paris Expo 


MacHack West Report 
Joel West 
Palomar Software, Inc. 
Contributing Editor 


My focus is going to be a little different than David Feldt's 
article (see “MacHack '87", MacTutor, August 1987), but then 
the conference was somewhat different than the one David 
attended, which we'll get to in a moment. 

I didn't hang around much with the parties or late-night 
hacking (if there was any), but got to hang around with some neat 
people and came away with a pile of interesting technical 
information. 

What's in a name? 

A rose by any other name would still smell as sweet — Romeo and 
Juliet 

Despite commonly being quoted out of context, Wil 
Shakespeare wasn't arguing that names were unimportant, only 
that they sometimes have more importance than they should. 

In this case, the name “MacHack West” caused lots of 
people lots of problems and nearly took the conference with it. 
I've talked to most of the principals and barely think I know 
what's going on. 

When you hear *MacHack West", you think of, “like the 
MacHack conference, only held on the West Coast.” At least I 
did, and thought it was a great idea, even if the middle of Oregon 
seemed a bit remote. It wasn't that simple. 

Itseems that the sponsors of the conference — Oregon State 
and Apple's Portland sales office — had nothing to do with the 
MacHack conference that had been run twice previously at the 
University of Michigan. And, as I gradually learned more about 
the conference, it seemed that more people were upset. 

When I saw Scott Boyd and Greg Marriott (aka the “Ма- 
cHax™ Group") at the Boston MacWorld Expo, they were 
spittin' bullets (and notjusta nearby windows, either). They said 
the way the Oregon folks had approached it was sneaky and 
underhanded, as opposed to the folks organizing the Michigan 
conference, who'd asked them permission. 

Of course, much of this may be associated with the friend- 
ships and perhaps even regionalism associated with the Mac 
community. Both the MacHax and their friends at ICOM (aka the 
TMON gang) were major players in organizing the Ann Arbor 
conference and didn't know anyone at the Corvallis conference. 

After it was all over, I talked to Aimee Moran, vice president 
of Expotech, Inc. Expotech is the professional management 
company that's running the Ann Arbor conference, along with 
other shows. It's her position that MacHack is a common-law 
trademark of Expotech, and they had threatened to shut the 
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Corvallis show down over use of the name. 

Some people I talked to in Cupertino (I'm not sure if they'd 
like to be named) were putting pressure on all parties to reach a 
reasonable accommodation. Both George Beekman and Mike 
Johnson of Oregon State told me they never had any attention of 
stealing any name, and all they wanted to do was put on a 
successful show. 

In the end, Moran said, Corvallis could use the name once — 

as long as it acknowledged the trademark — in order to avoid 

disruption of the show's planning. But, she said, it would not be 
called “MacHack” next year. 


Three Cheers for Tech Support 
My biggest impression of the conference was what a differ- 
ence the Apple people made to the show. If you'd pulled the 
Apple speakers, it would have been areal dud, certainly not worth 
the $218 flight to Portland and the 90-mile drive to Corvallis. 
Instead, Cupertino sent a large contingent. The names include: 


Jim Friedlander, tech support 

Chris Derossi, tech support (MacTutor Contributing Editor) 
Fred Huxham, tech support 

Jordan Mattson, MacApp evangelist 

Art Cabral, Mr. Pallette Manager 

Steve Maller, course instructor 


My understanding is that the Apple participation was ar- 
ranged by Mark Regan of the Portland sales office, who was 
somehow able to convince these guys to leave the grimy traffic 
jams of Silicon Valley to spend two days in a tree-lined college 
town in the middle of nowhere. None of them seemed to regret 
this decision. 

This was the first time I'd met any of the tech support people 
face-to-face. Some of them wasted no time in griping about the 
stupidity of some of my questions, but once we agreed on that, it 
was all downhill from there. Chris Derossi and Fred Huxham are 
both known to MacTutor readers from their past contributions 
and letters. Chris Derossi is also famous for his Chief Wizard" 
posts on the Mousehole BBS, being a long time ‘hole participant, 
and one of the founding board members of MacTutor. 


New Faces, New Attitudes 
One of the big changes at tech support is an infusion of new 
blood. I knew two of the most recent additions before they went 
to Cupertino, and, I must say, I’m impressed. 
One of the two is Mark Bennett, who, along with Charlie 
Jackson and Eric Zocher (president and VP of Silicon Beach) and 
myself, was one of the early leaders in the San Diego Mac User 
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Group. Mark wrote MacTools for the Copy II Mac folks, but then 
abandoned San Diego to join Ashton-Tate in L.A. Mark gave his 
notice after dBase Mac shipped. 

Mark is one of those guys who doesn't seem to care if it's 
never been done before (or maybe that makes it even more 
interesting). It certainly can't hurt for Tech Support to have 
members who have worked for third-party software developers, 
facing all the “Outside Apple" problems that the rest of us mere 
mortals face. Mark joins Derossi, another Ashton-Tate veteran. 

The latest new name is Darin Adler. Yes, Darin Adler, of 
TMONEUA fame. WhileIonly get to see him at the semi-annual 
Expo shows, Darin has impressed me as having one of the 
quickest programming minds I've ever met. He also makes me 
feel like any programmer is washed up at age 30 unless he 
accomplishes what Darin has in his early 20's. 

Overall, I was very impressed with the down-to-earth nature 
and grasp of reality shown by the tech support people I met. (For 
example, Jim said I'd done a great job on one of my recent 
articles.) And, it turns out, they are more in tune with the 
developer community than anyone else at Apple. 

In one of the sessions, Jim noted that Apple has worked hard 
to turn things around in the last 18 months. Actually, it seems to 
have been more recently than that. I can recall when I began on 
my book [Joel has a new book on MPW programming, which we 
highly recommend. -Ed] getting responses like “Buy this book 
from APDA [I had] and this is how you join APDA [I had]." 

I noticed the most dramatic change as the Mac II was rolled 
out, as tech support sought to bring everyone up to speed on new 
products on which Apple corporate placed a high priority. 
Everyone was learning, and it seemed as though tech support had 
a more open attitude about providing information. 


Compatibility isn't important 

(Thought that would get your attention; we'll get to it in a 
moment). 

Chris Derossi taught one session I sat in on, although, with 
bothJim and Fred kibbitzing from the front, it's notclear from my 
notes who said what. From now on, Derossi noted, there are 
actually three levels of answers to a “How do I do this ... which 
is undocumented?" They are: 

1. *Don't do that, don't do this, you're going to break." 
Examples include tabs in TextEdit, drawing in the menu 
bar, etc. 

2. "You don't want to do this because of this and that, but 
here's how..." They'll be sure to let you know how and 
why this will break later. 

3. "We can't help you.” For example, many low-memory 
globals are considered Apple proprietary, and can't be 
released outside the company. 

Chris noted that you don't always have to be compatible. 
Apple will be more likely to show you how to do risky things if 
it’s a one-time hack for yourself, rather than a commercial 
product. 

This, in fact, came up in regards to making the Apple video 
card put out NTSC output in interlace mode. I got my copy of a 
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little program from Allan Foster of Apple Specific, a consulting 
company with a funny name based somewhere in the Pacific 
NorthWest. (His partner said they'd been using the name for 
more than a year without any hassles.) The listing is Shown below 
in example 1. 

When asked about this specific instance, one of the tech 
support weenies said that they had the code, and would give it out 
as a #2, unsupported solution. However, he said they had 
nightmares that it would show up in a product on the shelf 
someday. 

On the other hand, if you break the rules, you're always on 
your own for future compatibility. ““We’re not to care if your 
program breaks," Derossi said, and that rule is even going to be 
enforced for the big guys, not just the little guys. For example, 
Microsoft applications break under A/UX, presumably due to 
their non-standard memory management. 

The specifics of compatibility were primarily those of Tech 
Note 4117. Tech Support has not been idle when supplying 
compatibility information, and there's a whole slew of it now 
available. 

All-in-all, however, I think this shows a marked improve- 
ment from the days of “Everything that you have a need to know 
is in Inside Macintosh." 


Twenty-five Color QuickDraw tips 

The most valuable talk I went to was offered by Art Cabral. 
Art, as someone who criticized the IIgs was quick to learn, was 
partof the GS development team. He also put together the Palette 
Manager in less than three months — which, as I noted in a 
previous article (“Sleuthing the New System File", August 1987) 
was too late to make the Mac II ROM. 

Art gave an alpha-to-omega talk on Color QuickDraw, 
which I thought was going to be pretty boring. However, I was 
soon scribbling away with all sorts of secrets that I thought others 
might appreciate. 

I collected a whole list of tips. (I might have even known 
some of this before, but never realized the significance.) Some 
of these were also made by tech support types, either during his 
talk, or later, but they all seem great to me. Note that at the time 
of the talk, System 4.1 was shipping and System 4.2 was in late 
beta, so some of the problems may have been (or will be) fixed. 

Here they are: 

1. CopyBits doesn't work right unless you have 
ForeColor(black) 

BackColor(white) 

2. Onanupdateevent, check the ctSeed to see if the color table 
for this window has changed. 

3. The ctFlags field (of a ColorTable record) is used to 
indicate a color table for an off-screen port, i.e., not on any 
device. 

4. If a pixel value larger than 65,535 is required, it is assumed 
that you are doing direct RGB values, and so the color 
table only needs two-byte pixel indices. 

5. The Palette Manager supports approximately 4,000 palette 
entries, not just the 256 colors normally in a color table. 
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You can also use subranges of a palette at different times 
in your program. 

6. CopyBits will be much faster if the ctSeed is the same on 
both ports. 

7. One way to speed a CopyBits is to force the seeds to be the 
same. Forexample, if you're copying toan offscreen port, 
make it the same as that of the source window. 

8. In 256-color mode, each CopyBits adds a 1K color table to 
the picture. The less CopyBits calls, the better; 20K-40X 
worth of bits at a time is a reasonable size. 

9. The Palette Manager looks for a color within the range of 
a tolerant color and, if it finds none, creates a new color 
exactly the same as that requested. 

10. The Palette Manager supports explicit colors, correspond- 
ing to the pixel value that's actually going to be stuffed in 
the screen PixMap. It ignores RGB value and leaves the 
index to be interpreted by the video card as a color in the 
device's color table, so, for example, an index of 0 will 
draw white. 


11. Colors drawn in the desktop are not reserved by the Palette | 


Manager; but 

12. The six colors of the Apple in the menu bar are automati- 
cally allocated by the Palette Manager; colored menus 
(‘mctb’ resources) are not allocated. 

13. Region calculations are used to keep track of which colors 
to keep; one of the goals was to display the Cheryl Tiegs" 
image well. 

14. The standard 256-color clut contains every combination 
of six intensities of red, green and blue, plus 16 different 
intensities of pure red, green, blue and white. There's 
some overlap, which is why it's 256 and not 280. 

15. If a window is animating colors in the back, it may lose its 
colors to the frontmost window. Art showed his Spinna- 
ker program, which kept putting up windows of animating 
colors and was both an impressive demo program and test 
suite. (He borrowed a monitor from a developer who 
brought a Mac II so he could have two monitors with 
different color depths). 

16. When the Palette Manager makes a change that affects a 
window, it generates an update for that window. If the 
window had been saving the screen bits, it should use 
CopyBitstoputthem back, because the actual indices may 
no longer be valid (because the color table might have 
changed.) 

17. The Palette Manager gives priority based on entry type, 
then on a first-come, first-served basis. In 16-color mode, 
priority is given to: 

* The first 16 animating colors; if none, 
• The first 16 tolerant colors. 
Other colors come later. 

18. Apple is working on gray-scale support for the Laser- 
Writer printer driver. 

19. There's a bug in HSL to RGB conversion, so do the math 
yourself. 

20. A flashing marqueé-style effect is done by the selection 
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rectangle in MacPaint in b&w mode using XORing. To do 
it in color, save the pixels of the four lines of the rectangle 
and then flash the border. 

21. The TI color chip (TMS34010) does its additive colors in 
pixel space, by adding the pixel values; color QuickDraw 
does it in RGB space, by adding the individual red, green 
and blue values. 

22. The Palette Manager allows for direct color, that is, 
display devices that are not limited to the size of the 
indexed color table. 

23. The manager was written from February to April 1987, 
and wasn't integrated with the rest of the Toolbox until 
three days before the freeze date. One person worked on 
the Palette Manager and two on the Window Manager to 
complete the integration. 

24. To use the inversion operators in color, there are several 
conditions: 

* The color table begins with white and ends with black; 
* The foreground color is black and the background color 
is white. 

25. The OpColor trap is used for additive (mixing) color 
modes. 

A/UX 

Unfortunately, I had to miss most of Fred Huxham's talk on 
A/UX, because I had to attend my own talk instead. (I talked 
about PICT and other graphics formats, which may someday 
appear in an expanded form in Resource Roundup.) 

When I arrived late, Fred did say that special dealers will be 
selling A/UX, and they will be requiring special training. 

He also said that AST's $1,000 four-port serial port for the 
Mac II will be required to run AppleTalk. Why? Think about it 
a minute. AppleTalk shoves characters on the bus every few 
microseconds. As a result, it is entirely done with 68000 polling 
loops, rather than being interrupt driven. There's no way that a 
UNIX kernel would settle for being shut down (with interrupts 
off) for that long, or if it was, that it would provide reasonable 
performance. Instead, AST has a board with a 68000 on it, 512K 
RAM and two SCC's, fora total of four ports. Idon'tknow much 
about how it works, but Fred indicated that A/UX was being 
bundled with AppleTalk drivers for the AST board. The board 
also has a 50-pin connector with a mammoth cable breaking out 
into four DB-25's, according to Fred. Awful as they are, give me 
the same connectors as I'm already using on my cables, those 
stupid MiniDin-8's. 

Hype-Our-Card 

Don't get me wrong. I've been trying it out developing 
Palomar's invoicing system, tracking our pr/advertising effec- 
tiveness and receivables. I think HyperCard is great and, after 
MacPaint and HyperCard, I wonder what Bill Atkinson can ever 
do for an encore. 

However, the nonstop hype for the product (starting with a 
MacWEEK article on the Boston Expo that claimed HyperCard 
was hot while MultiFinder was not) was beginning to get on my 
nerves. Enter the conference keynoter. 

He was Danny Goodman, author of the best-selling book on 
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HyperCard. I was told Steve Wozniak (originally billed as the 
keynote) cancelled for personal reasons, hopefully not having to 
do with the controversy. Wozniak was and is a hacker; 
Goodman, as he was the first to admit, is not. Some comments 
I heard questioned whether an avowed non-programmer was an 
appropriate speaker for such a conference, but he was, admit- 
tedly, an expert on a subject on a lot of people's minds. 

Goodman noted that HyperCard put Macintosh program- 
ming in the hands of non-programmers, "guys like me." It'sa 
tool for very specific needs, not what would be used for develop- 
ing commercial applications. 

However, there's room for programmers in developing 
XFCN's and XCMD’s. (These resource types for separately- 
compiled code that can be used to add functions and commands 
to the HyperTalk language.) He urged development language 
vendors to supply sample code, since the Apple-supplied code is 
for MPW only. 

If you do plan on developing commercial stacks, Goodman 
argued that professional design should be used for the stack 
layout. Otherwise, it's easy to develop "junk" that doesn't do 
anyone any good. 

Market opportunities include: 

• Electronic publishing, such as CD-ROM; Goodman cau- 
tioned against a dry transcription of the information, 
urging “sizzle” in the dressing; 

* University training, like an Ohm's law simulation; 

* Vertical markets; 

* Controlling specialized peripherals. 

Since HyperCard's password protection is not (and was not 
intended to be) very strong, developers should protect their 
proprietary interests using compiled code, rather than Hyper- 
Talk. 

This and That 

For several months I'd wondered why my Peak 30Mb hard 
disk wouldn't boot from the Mac II. The one benefit I got from 
shipping my Mac II and Apple monitor to the show was getting 
the disk to work finally. Ron Aldrich (of Carl Nelson & 
Associates) installed his Adaptec 4070 Software Kit on the Peak, 
and, voilà, it worked. 

According to his fellow technoids, Bo3B (the “3” is silent) 
Johnson of Tech Support has put together a hack that allows for 
50+ DA’s to be installed at once. It may show up in a future 
system. 

Each DA should have a window, even if it's invisible. This 
helps the Layer Manager handle MultiFinder-related interac- 
tions. 

If youuse screenBits.bounds as a parameter to DragWindow 
(and GrowWindow?) the Window Manager knows that you 
mean all screens on all devices on the Mac II. This works as long 
as the dimensions are close enough. 

. . Device drivers should be ready to run in 32-bit mode “soon”; 
other programs can drag along using 24-bit kludges for a while 
longer. 

The Level-1 upgrades to the Mac 512 are still available. The 
Level-1 upgrade (disk, ROM) should be available from dealers 
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without buying the Level-2 (motherboard) upgrade. 

Several of the Apple panelists offered cautionary remarks 
about believing what you read in one of the Macintosh weeklies. 

Some questioners asked why HyperCard doesn’t follow 
Apple’s own interface guidelines (like no windows on the 
342x512 screen). The answer was, basically, Bill Atkinson does 
what he wants. 

Although Apple got its share of criticism at the “Bash 
Apple” session, the largest share of the barbs during the two days 
came from Andrew Singer from Think (now Semantec). I don’t 
know whether Singer enjoys being controversial or just had a lot 
to get off his chest, but he seemed to go out of his way to criticize 
Apple. 

LightspeedC splits benchmark contests with MPW C, 
Singer said. This didn’t say much for MPW, since Think knows 
how much better its compiler could be, he said. 

He said Think’s evaluation of MacApp showed that it wasn’t 
useful for real programs. (Several MacApp users, including me, 
disagreed). He called on Apple to instead to develop an Appli- 
cation Manager that could be used for all programming lan- 
guages. 

Singer argued, in fact, that the whole area of object-oriented 
programming had been oversold. Despite MacSmalltalk being 
nearly given away to universities, the language has “failed” 
because it addresses the mindset of only a few people. 

Apple doesn’t realize this, according to Singer, because it 
has some of the “religious messiahs” that created Smalltalk in the 
first place, including Larry Tesler and Dan Ingalls, formerly of 
Xerox PARC. 

More To Come? 

I'd never been to the Beaver State before. Corvallis is in the 
sticks, but it’s difficult to imagine a more pleasant setting then a 
small, plush college town in the middle of nowhere, and the early 
fall weather certainly cooperated. Even if it would be easier and 
would attract more people, holding it in Silicon Valley or 
Berkeley wouldn’t be quite the same. 

The West Coast certainly needs an informal, regular techni- 
cal conference like MacHack West. The Boston and San Fran- 
cisco shows are zoos, and there’s no way that any technical 
session can have the intimacy and unhurriedness necessary for a 
free exchange of ideas. 

So, whatever it’s called, there’s certainly a demand for such 
aconference in the future. Let's hope that when the Fall of 1988 
rolls around, there will be another conference and we'll all have 
a chance to get together again. 


Example 1: NTSC video on Mac Il 


UNIT Interlace; 
(* Interlace mode for Apple Video Cerd; 
adapted to MPW Pascal by Joel West *) 


INTERFACE 
PROCEDURE SetInterlace(Slot: Integer ); 
PROCEDURE Clear Inter lace(Slot: Integer); 


TYPE 
RegArray = АВВАҮС0.. 151 OF LONGINT; 
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RAPtr = “RegArray; 
IMPLEMENTATION 


PROCEDURE SetInter lace(Slot: Integer); 
(* Set to NTSC Video *) 
VAR 


CardPtr: RAPtr; (* Pointer to array of longints *) 
LongPtr: ^LONGINT; 
Dummy: Longint; 
BEGIN 
(*  CerdPtr :- $100000L*Slot *$80000L ; 
card = $00100000*slot %%80000 *) 
CerdPtr := POINTERCBSLCS10t,20) *$80000); 


(* Due to “byte lanes” (see Slot Manager), we only 
write a byte of each 32-bit long integer *) 


CardPtr*(6] := $FF; 
CerdPtr^[1] := $48; 
CardPtr^(2] := $FF; 
CerdPtr^[3] := $F7; 
CerdPtr^[4] := $9F; 
CerdPtr^[5] := $14; 
CerdPtr^(6] := $C4; 
CardPtr^(7] := $E6; 
CardPtr^[8] := $FA; 
CerdPtr^(9] := $F7; 
CardPtr^[10] := $E5; 
CerdPtr^(11] := $F1; 
CerdPtr^[12] := $7B; 
CerdPtr^(13] := $F1; 
CerdPtr^[14] := $01; 


CerdPtr^[15] := $06; 
LongPtr := POINTER(BSLCS10t,20) *$C0000); 


Dummy := LongPtr^; (% Must be а Longint reference х) 


END; 


PROCEDURE ClearInterlace(Slot: Integer); 
(* Set To Mac Normal video *) 
VAR 
CerdPtr: RAPtr; 
LongPtr: ^LONGINT; 
Dummy: Longint; 
BEGIN 
CardPtr := POINTER(BSLCS1ot,20) +680000); 
(* card = $00100000*slot +$80000 *) 


CardPtr*[8] := $FF; 
CerdPtr^(1) := $88; 
CardPtr*[2] := $FF; 
CerdPtr^(3] := $F7; 
CerdPtr^(4] := $0F; 
CerdPtr^[5] := $14; 
CardPtr*(6] := $88; 
CerdPtr^(7] := $89; 
CerdPtr^[8] := ФҒА; 
CerdPtr^[9] := ҒҒ; 
CerdPtr^(10] := $E1; 


CerdPtr^[11) := $E9; 
CerdPtr^[12] := $79; 
CerdPtr^[13] := $69; 
CerdPtr^[14] := 

CardPtr^[15] := $02; 


LongPtr := POINTER(BSLCS1ot,20) *$80000); 
Dummy := LongPtr^ ; 


END; 
END. 
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Apple Expo - Paris 
Jörg Langowski 
MacTutor Editorial Board 


Itook the opportunity to meet David and Laura at the Apple 
Expo in Paris, and see what the European Mac scene is up to. In 
fact, I won't repeat news that you'll already have heard from 
Boston's MacWorld Expo, like the introduction of Hypercard 
and Juggler (oops... MultiFinder is the word). Therefore the 
following lines are nothing but a very subjective and limited 
selection. 

The Editor Speaks! 

David gave a speech at the developer's conference which 
was very well received, recalling the history of personal comput- 
ers starting from the Altair 8080 and ending with the obvious 
culmination point, the Mac. In a reply to recent changes in Apple 
policy towards developers, trying to make developer's contracts 
more hard to get, he recalled the beginnings of Mac developing: 
The broad base of programming knowledge that exists now 
would not have been possible if one would have been stuck with 
Apple's policy in 1984 that said that the Mac wasn't really a 
programmer's computer. In fact, those who didn't buy this policy 
were those who advanced the ‘opening’ of the Macintosh and 
made it into what it is now. This fact seems almost trivial 
nowadays - but it should be repeated so that it isn't forgotten. 

[There is considerable confusion in France over the policy 
changes by Apple as to who will qualify as a developer and this 
generated the most heated debate. Instead of qualifying compa- 
nies or individuals, developer's will be qualified on a project 
basis and will remain certified for only as long as a specific 
project is in development. The potential loss of developer status 
sent many programmer's into a frenzy since there is a general 
feeling in France that without Apple’ s direct involvement and 
support, a programming project doesn't stand a chance of 
getting off the ground. French developers are much more de- 
pendent on Apple than their US counterparts. -Ed] 

David also pointed out that being in Europe should not keep 
you from writing for MacTutor - in fact we know there are many 
of you out there that have good material in their drawers but are 
for whatever reason hesitating to write it up. Well, DO write it up, 
it doesn't even have to be all that nice and slick, we'll edit it. 
David and I have agreed that European contributors should send 
their articles directly to me. Even though my address is printed in 
the masthead, I'll repeat it here: 

Jórg Langowski 

EMBL, c/o ILL, 156X 

F-38042 Grenoble Cedex 

France 

I'm looking forward to your contributions. 


TNT DA 
One product that was introduced at the Apple Expo deserves 
special mention. It is a desk accessory called TNT. No, the name 
doesn't mean that you create bombs with it; on the contrary, the 
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(first) version that I have is remarkably bomb-free. TNT is short 
for Think ‘n Time, and at first glance the thing resembles an 
outline processor like Acta. I am writing this column with it. I 
don't know whether you find my column more structured this 
way (I have my doubts), but I love TNT. 

TNT displays the hierarchical structure of a document in a 
nice little tree chart, with icons at each node that change depend- 
ing on whether the chapter has sub-chapters, has text in it or not. 
Clicking on the corner of the icon will get you into a powerful 
small editor, much like miniWriter, to edit the text associated 
with that chapter. You can move branches of the tree to and from 
other branches at the flick of a mouse, and scroll through the 
whole outline of your document using either scroll bars ога “hand 
cursor' like in MacPaint. Of course, the outline can be saved as 
it is, as a text file, and even as a MORE document. It may be 
printed as text, or in form of a tree indicating the structure. 

But more (pun intended): each item of the outline may bear 
a date, which makes TNT a nice planning aid; there is even an 
option to automatically generate a calendar outline structured by 
months and weeks. On top of that, each item may contain one 
number, and simple calculations may be carried out to store - for 
instance - the sum of the numbers in all sub-items into the next 
higherlevelitem. This means that simple spreadsheet-like opera- 
tions can be done by TNT; one example on the disk maintains a 
portfolio with items in different currencies. 

This gem has replaced Acta, MockWrite, and Calendar in 
my desk accessory menu. Very much recommended. It is distrib- 
uted in Europe by Emday, 71 rue des Atrebates, B-1040 Brussels, 


Belgium, phone (32) 2-733-9791, and in the US by Mainstay, 
5311-B Derry Ave., Agoura Hills, CA 91301, phone (818) 991- 
6540. Its price is somewhat less than $100. 

Apple introduced the wide carriage Imagewriter LQ, which 
seems to be a good alternative to the Laserwriter; some people I 
talked to even liked it better because one can add up to three sheet 
feeders. 

Winsoft (local heros from Grenoble) introduced a multi- 
lingual word processor which uses the Script Manager and 
allows you to type in Arab and Latin scripts simultaneously. The 
text processor itself, also, seems very well made, compares well 
with products like MS Word or WriteNow. They also work on (or 
have?) a version for Kanji script. 


DDA Brings APDA to France 


The last thing that I'd like to mention is that Serge Rostan 
(I.Development, see his address in any of his MacTutor ads) has 
started DDA (Documentation Developpeurs Apple), the equiva- 
lent of APDA in France. He'll be offering the complete product 
line of APDA, has most of it in stock (so no waiting, overseas 
phone calls or Fed Express charges) and will sell it at US$ prices, 
applying the French Franc to US$ exchange rate, which is 6:1 at 
the moment. This means we'll have APDA materials cheaper 
than at APDA itself, how's that for a change. [Serge Rostan is a 
great friend of the French Development community and a Mac- 
Tutor fan! We wish him well. -Ed] m 
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APL Vectors 
APL Returns to the Mac 


STSC APL*PLUS, Other APLs, 
and Some Utilities 


Nearly two years of being distracted is a record even for me, 
but I’ve started іп on APL again, and with some luck maybe I can 
keep it up for a while this time. A lot has happened in the last few 
months — there are now four different APLs for the Mac, three 
commercial and one shareware. PortaAPL has become STSC 
APL*PLUS, APL.68000 has finally been released, MacAPL is 
available for those on a budget, and a shareware APL from 
France, APL 90+ has turned up. This month I'll give brief 
descriptions of each them, with detailed coverage of STSC APL, 
which I’ve used the most. 


* APL.68000 ($295, Spencer Organization, Inc., 366 Kin- 
derkamack Road, P.O. Box 248, Westwood, NJ 07675, (201) 
666-6011 ) is competing directly with STSC as a full powered 
language with at least some access to the Mac toolbox. Unfor- 
tunately I haven’t been able to see it, and since it has a $295 list 
price I can’t afford to buy it just for fun. But the rumors on the 
net are that it’s fast since it’s written in assembly, and solid. It 
follows the ISO standard except for the file functions— they use 
some made up symbols instead of the usual quad functions 
(UFTIE, OFCREATE), which not only makes programs harder 
to read, but complicates porting programs in both directions. 
They get into more of the Mac toolbox than APL*PLUS does, 
real windows and dialogs for example. I'll try to get a good look 
at it soon so I can give you more information. 


* MacAPL ($125, Leptonic Systems Co., 405 Tarrytown 
Rd. #145, White Plains, NY 10607) isa relative newcomer, writ- 
ten by Michael C. O’Conner, author of Layout Editor. It doesn’t 
yet support the entire language, and it doesn’t access the toolbox, 
but it has some very nice features. It provides a run-time system, 
sO you Can distribute stand-alone applications, and it has the 
nicest user interface of the lot. You can open more than one 
workspace at a time and the editor is done properly. There is a 
function to put text and pictures into the clipboard. A demo 
version that can do everything but save a workspace is available 
on Compuserve, Delphi, and in many public domain libraries. I 
was surprised at how fast it was - it did my harmonic benchmark 
(*/*v10000) іп 23 seconds. It's well worth getting hold of a 
copy of the demo just to get a little of the flavor of APL. 


* APL 90 ($85 shareware, SYNC, 12 Place Hotel de Ville, 


42000 Saint-Etienne France) is a straight APL from France. It 
is ported from a mainframe APL written in C at the Ecole des 
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Text Utilities 


Mines de Saint-Etienne by Jean-Jacques Girardot, Francois 
Mireaux and Sega Sako, and is full APL, conforming to the ISO 
standard. It has a few Mac features, including a row of buttons 
along the bottom of the screen to change keyboard (ASCII vs. 
APL), debugging (NONE, TRACE, Macsbug) and to show the 
time and cursor position. Unfortunately there isn't a full-screen 
editor; you have to use the standard clumsy APL del-editor. If 
you're interested in doing number crunching and don't care 
much about immediate access to the toolbox, this is a good one 
to look at. Girardot plans to add APL2 features (including nested 
arrays, ambivalent functions, machine language functions, as 
well as some object-oriented extensions) by the end of the year. 
Since APL 90 comes from France, it has a few keyboard prob- 
lems - they very kindly put in a UK keyboard option, but nota US 
option. I haven’t bothered to patch the keyboard resources for my 
copy yet, since I don't use it regularly, but it shouldn't be hard to 
do. One warning - the 1.0e version that I have is incompatible 
with System 4.1. 


*STSC APL*PLUS ($395, STSC Inc., 2115 East Jefferson 
St, Rockville, MD 20852) is the new name for PortaAPL. 
PortaAPL still lives as a company, but has licensed it’s Mac APL 
to STSC. PortaAPL still does all of the programming, and is 
bringing the interpreter into line with STSC's other APLs for 
IBM-PCs and mainframes, while STSC handles documentation, 
marketing, support, and utility libraries. 

The package you get contains a 200 page User's Guide, 300 
page Reference Manual, an APL tutorial (APL is Easy), key 
Stickers to help youlearn the keyboard layout, and two disks, one 
with the interpreter and the other with several utility workspaces. 
Price is $395 list, with educational discounts. The license 
agreement is the standard *We have all of the rights, you have all 
of the responsibilities’ variety. Registration entitles you to ‘free’ 
telephone support (but it’s not a toll-free phone number), and a 
quarterly newsletter. The phone support has been mostly helpful. 
They are very good at answering APL questions, but have more 
trouble with Mac specific problems. The people I’ve talked to 
have all been IBM-PC types. 

The documentation is basically OK. The books are well laid 
out and easy to read. The Reference Manual has an excellent 
APL language summary that I wish I’d had available when I was 
first starting, and the User’s Guide can easily be read through in 
a couple of sittings to get an overview of the system. The 
organization isn’t great though. They went to some effort to not 
duplicate any information, and the indices aren’t complete. You 
have to go from one book to another a lot to find out enough about 
some things to use them. And some topics are just plain hard to 
find; for example, the OSFOPEN and OSFSAVE functions for 
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invoking the Standard File package aren't anywhere under 
‘files’, but are listed under ‘dialogs’ — an obvious confusion on 
their part about what dialogs actually are. All of the appendices 
in the User's Guide (the atomic vector, error messages, system 
limits) really should have been in the Reference Manual. The 
level of explanation is somewhat uneven as well. There is gory 
detail about what a file is, but you're expected to already know 
about forks and resources. Even the name of the program is 
confusing at times — they refer to the STSC APL*PLUS System 
file often, and they mean the interpreter, not the Mac System file. 

The tutorial book APL is Easy isn't very useful. I found the 
tone of it to be patronizing, and almostevery example is business 
related. (My brain clicks off whenever I see words like ‘amorti- 
zation’ and ‘sales’.) It is written for the IBM-PC version of 
APL*PLUS, witha page or so of corrections for the Mac, and the 
highlighting of text that you should type in is distracting. Buy a 
copy of Gilman and Rose instead (APL: An Interactive Ap- 
proach, Leonard Gilman and Allen J. Rose, John Wiley & Sons, 
ISBN 0-471-09304-1). They have business examples too, but 
they throw in enough math and computer science to keep it 
interesting. 

The Mac interface is a little better than before, as is the 
editor. The full screen editor now has a horizontal scroll bar for 
long lines, and you can cut and paste more than one line at a time. 
There is no search function, so changing a variable name can be 
tedious. Cursor placement is tricky; if you click once between 
characters, the character to the left is highlighted, and I mangled 
a lot of text by typing too fast until I learned to click on the letter 
to the right. Double-clicking doesn't select a word as it should, 
either. The scroll bars are present in the main interpreter window 
even though they aren't active, and you can't make them go 
away. They reduce the useful area of the screen, and look untidy 
when doing graphics. You can still only cut and paste one line in 
the main window. 

The font is better (it no longer conflicts with San Francisco), 
but isn't perfect. There are three sets of APL fonts (narrow, wide, 
and italic) and a downloadable Laser font, but since each family 
has the same ID numbers, you can't have them all installed at 
once. Youhave to use the Config workspace functions to change 
the default family and size, and the change doesn't take effect 
until the next time you load the interpreter. The font size you 
choose affects allowable values for the OWINDOW function, 
which causes programming problems. Worse, if you install the 
font in your system file so that you can edit stuff in MacWrite, etc. 
the keys you need to get the APL characters are wildly different 
from what you use in APL. Why they couldn't arrange things to 
be consistent is beyond me. I'd fix it with a font editor, but that 
would complicate transferring files to friends. 

Toolbox access hasn't changed appreciably from the older 
PortaAPL version. Quickdraw, menus, mouse functions and 
some resource functions are still there as utility workspaces. 
What STSC refers to as a ‘window’ is more appropriate toan IBM 
computer — just a restricted region of the screen. 

The keyboard layout is very nice. You can choose between 
a standard APL layout, and the ‘unified’ arrangement, in which 
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the APL characters are typed in with the option key. Lowercase 
is supported for object names, which is a great improvement over 
the standard underscored characters. 

Mainframe versions of APL*PLUS have many of the APL2 
extensions (newer editions of Gilman and Rose cover APL 2 and 
other common extensions of APL), and I had been particularly 
hoping for nested arrays. Butnestedarraysare memory hogs, and 
STSC is trying to keep the microcomputer versions as compat- 
ible as possible. Intel processors just couldn't handle the load 
until recently with the ‘386, so we'll have to wait for awhile. 
Nested array are on the list though, so with luck we may have 
them before too long. They do provide dyadic up- and down- 
grade, which makes alphabetizing in any order you chose ex- 
tremely easy, and a few other APL2 functions. 

The stability of APL*PLUS is pretty good. If you ever use 
desk accessories, you should set the HEAP SPACE value with 
the Config program to at least 100k. I had some crashes until I 
figured out that APL allocates as much memory as possible into 
one big non-relocatable block in order to handle large arrays. 
HEAP SPACEtells APL how much memory to leave free for the 
system, printer divers, and desk accessories. The default value is 
set to only 40k, which is barely enough for the laser printer driver 
or small DAs. On a Mac Plus, 100k is a good value; on a 512k 
machine, 70k is a reasonable compromise that still gives you a 
180k workspace. 

Of the three bugs I’ve found, one is minor; the DSOUND 
function timing is from 2096 to 80% too long, and the variation 
is random. This makes music programming impossible, but the 
control DSOUND allows (pitch, volume and duration, and only 
one voice) is too limited for real music anyway. The other two 
are more serious. One isa DSFSAVEproblem. If you try tocreate 
a file that already exists, the “Ро you want to replace?' dialog 
comes up normally, but UNCREATE will refuse to create the file, 
giving an filename error. This can be worked around by trapping 
the error, deleting the old file, then continuing on, as I do in the 
utility functions below. The third bug is the most serious: 
ONTYPE, which gives a file type and creator to a Mac file, 
crashes the system randomly. It crashes much less often (about 
half the time instead of 90% of the time) if ОТРАСЕ is turned on. 
STSC knows about the bug, and it should be fixed in the next 
version. Meanwhile, there is no workaround; you must use a 
utility such as Disktop, or FileInfo to manually set the type and 
creator. 

Overall, I like APL*PLUS. The Mac interface needs a lot of 
work, and I have a list of quibbles, but it's useful and fun, and 
mostly works as advertised. The support is good, and I think that 
new versions will fix the problems and add more goodies (nested 
arrays, please!!) [Note: APL*PLUS does not work on a Mac II, 
although itis rumored a beta Mac II version is in the works. STSC 
readily admits all their effort and interest right now is on the IBM 
version, which is up to version 7.0, as opposed to the Mac 
product, which has never left 1.0!-Ed] 

Text Utilities 

On to a few utilities that I wrote to help with getting 

information into and out of APL*PLUS. These are useful for 
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including APL functions in a text file (like this article, oddly 
enough) without having to retype everything. It's possible to do 
this via the clipboard, but I don't care for the extra time it takes. 
Also, by reading and writing directly to a file, you can handle 
larger objects without running out of heap space. A note on one 
of my conventions — since lower case is now allowed in identifier 
names, I have used lower case exclusively for any global function 
name or variable. This makes it much easier to pick out my stuff 
from the utilities and routines that STSC provide, and that you 
have to leave lying around in the workspace to get anything done. 
And since everything except system functions are case sensitive, 
Idon'tneed to worry aboutaccidentally using one of their names. 

The first, lister, is based on the APL*PLUS LISTER pro- 
gram which dumps a workspace to the screen. I've changed it to 
dump toa file instead. Itignores all locked functions completely, 
and the format for the listing of variables is different. All of the 
local variables in the function end with a double underscore. 
Since local variables and functions are ignored by DIDLIST (at 
least before you actually use a local variable), I wanted variable 
names that wouldn't shadow global variables. (Note that since 
lister itself is declared local, it will not dump itself to the file.) I'm 
unlikely to use the double underscores under other circum- 
stances, so lister should see everything in the workspace. “lister” 
shows up one of the big problems I’ve found with APL. Redi- 
recting I/O can be a real pain compared to Fortran. I haven't yet 
found an easy way to say 'send stuff to a file instead of the screen 
until I say otherwise.' If you write a numeric variable to a file, 
it's sent as binary unless you explicitly tell it to be text by using 
the format (ғ) function. 


Another complication is that since APL*PLUS is written in 
С, it uses newlines (line-feeds, OTCNL) instead of the usual car- 
паре returns (OTOCR) at the end of lines. This is assuming that 
there are any end of line markers at all — character vectors often 
have them, character matrices usually don't. My solution is to 
first find all newlines and change them to returns, then if the 
variable is a matrix, I append returns to the end of each row. I 
have a separate function replace char to change any character 
into another that makes the substitution easy. 


"lister" first finds an unused file tie number, then calls 
OSFSAVE to get a file name. If cancel is selected, filename. 
will be an empty vector, and lister will exit. If an existing file 
name is chosen, you have to try to create the file, trap the resulting 
error, then delete the old file yourself. After you have a valid file 
name, just call ONCREATE again and continue on. 


To list the functions, I use OVR, the visual representation. 
This produces a character vector with line feeds, and gives the 
line numbers. If you don’t want line numbers, you can use OCR, 
the canonical representation instead; it’s a character matrix, and 
you'll need to append carriage returns to each row. Variables аге 
listed with the data type, then the variable name, and if it isn't a 
scalar, the shape. The data itself comes on the following lines, 
one row per line for dimensions higher than one. 
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"replace char" isa general character replacement filter, and 
is a nice example of the membership (€) and compress (/) 
functions, and indexing. The right argument is a character vector 
whose first element is the character to be replaced by the second 
element. Anything else in the vector is ignored. Line 9 creates 
a boolean vector (loc) with ones at every occurrence of су[1]. 
t x /shape creates a vector of 1 2 ... N, where М is the number 
of elements in the object. Multiplying by loc selects out the 
values that contain cv[1], and loc / compresses out the zeroes. 
"Joc" can now be used as the array index for text. There is one 
problem with this algorithm: it uses a lot of memory. Iota uses 
4 times as much memory as the text it’s working on. On a Mac+ 
this isn't too bad - in an empty workspace I can easily work with 
a 100К character vector. 

The next two functions let you transport character data into 
and out of APL without having to use the clipboard. "text. file" 
takes a character vector or matrix, converts newlines to returns, 
then writes it to a file. “Ше text" reads a text file into a character 
vector, converting returns into newlines. This makes it conven- 
ient to write up help screens in Mockwrite, or any other editor in- 
stead of the marginal built in editor. Character vectors take up 
less space than matrices as they don't have to pad out to the end 
of each line, but character matrices are often easier to manipulate. 
Note the check for available memory before actually reading the 
file — since file textcalls replace char, you need to allow for the 
additional memory it needs. 


APL BBS 


As an end note, some news about a BBS for APL users. 
BBS\APL (1-301-340-6296) is free (except for phone bills!). 
Now it’s oriented mostly towards IBM-PC users, but I’m sure we 
canchange that. The BBS is run by Murray Spencer in Gaithers- 
burg MD, andisarats nestto navigate around, but there are plenty 
of special interest groups, including specific APL systems, 
Amiga, and academic, so it shouldn’t be hard to get them to 
support Macs. Give them a call and let them know that the IBM- 
PC is on the way out! 
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Fig. 1 PlotDemo in APL 
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V text = fille text ;tie ;name ;size 
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a imports a text file to a character vector, converts CR to LF 
a uses replace char 


tie = CL / 0,ONNUMS >) - 1 a get unused tie number 
name + DSFOPEN 'TEXT' a get filename 
> ( name = '' )/0 a exit if empty filename (cancel) 
name [INTIE tle а open flle 
size = ONSIZE tie a find out how big it is 
> ( size > OWA + 6 ) / MEMORY а if too big, go to MEMORY 
text = ONREAD tie, 82, size, 0 а read in the whole file 
text = text replace char OTCCR,OTCNL а convert CR to LF 
ONUNTIE tie а close file 
EXIT: > 0 A exit 
MEMORY : 
'Not enough memory to read this file' A print message to screen 
ONUNTIE tie a close file 
V 
V lister ;fns__ ;var__ ;text__ ;x__ ;lister ;tle . ;name__ __ ;UELX 


Т 
а list all function and variable names and definitions to a file 
a uses replace char 


UELX = ' > ЕРЕ! a trap errors 

var__ + DIDLIST 2 a get list of variables 

fns__ = DIDLIST 1 а get list of functions 

name . + 'Save as ...' OSFSAVE 'Listing' a get file name 
^-(name = '' ) / EXIT а exit 1f empty filename (Cancel) 
tie « (L / 0,0NNMS ) -1 а get an unused tie number 
CREATE: 

name . ONCREATE tle. а create file 

a 'QEDITEXT' ONTYPE tle . a assign file creator and t 


ype 
а Ccommented out until ПМТҮРЕ is fixed) 


> (0 е о fns ) / L4 a If no FNS, skip to VARS 

Li: > = о text__ + OVR Ғав. ІПІО;1) / L3 a If locked fn, skip it 

text__ = text replace char OTCNL,OTCCR a replace LF with CR 
L2: С text. ,ПТОСЕ ) ОМАРРЕМЮ tle . a output function to file 
L3: > (~ 0 e о fns__ = 1 0% fns?) / L1 a drop first name from list 
14: > (0 є о var 2 / L7 a If no variables, last line 
L5: text__ = (Чехї__ # ' ') / text = var__[0IO;] а remove spaces 

X + 9 text. a get data for object 

a make ID line of type: [INT] variable nam 2 4 34 0 

type | = '[([',C,C11 82 323 645 =ODR x__)# 4 3 @'BITCHRINIFLT'),'] ' 

text. < type__, text__ 

(text__,' ,CC0 # оо X D / <ғох 2, "0" >, ОТССВ) ONAPPEND tie__ 

((ғх о, OTCCR) ПМАРРЕМО tie e. a write object to file 
16: > (~0 є о var = 1 0 + уаг__) / LS A see if thereas more to do 
L7: UNUNTIE tle . a close flle and quit 
EXIT: > 0 
ERR: а check for flle name error 

> (ПЕПЕ NAME ERRORa £ 15 ^ ПОМ) / OTHER, ERR 

name . [NTIE tle... а open flle 

name - ONERASE tle . a delete file 

> CREATE 


E, cu a displays error message and quits for any other error 


V 
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v t = text replace char cv ;loc ;shape 
a filter to replace all occurrences of one character with another 


text сап be either a vector or a matrix of any shape 


t returned with the same shape as the original text 
Warning: uses a lot of memory! (4 times as much as text takes up) 


а 
а 
а су[21 character to replace cv[1] 
A 
A 


shape = o text 

text + ,text 

loc = text e cv[1) 

loc + loc / loc x v x/shape 
Тех ГІОСІ = cvI21 

+ ~ shape o text 


remember the original 


DDDDDD 


do the replacement 
return value reshaped 


v 


V text flle text ;name__ ;tie__ ;DELX 
A writes a character vector or matrix to a file, converting LF to CR 
а а character matrix gets a CR added to the end of each row 


A text can be any shape 
A uses replace_char 


shape 


ravel text to a vector 
find all occurrences of cvI[1] 
create list of positions of cvI[1] 


to original 


ПЕГХ + ' > ERR ' A error handler 
tie +| ( L / 0,0ONNUMS 2-1 A get unused file tie number 
name | ~ ‘Save text as ...a OSFSAVE 'Text’ get filename 
> (nam = '' ) / EXIT а exit if empty filename (cancel) 
CREATE: 
name__ ONCREATE tie 7 A create file 
A 'QEDITEXT' UNTYPE tie__ A give it a creator and type 
text = text replace char OTCNL,OTCCR a convert LF to CR 
> С (Соо text) = 1 ) / L1 A if it a vector, skip next line 
pue < text , Со text)[1] o OTCCR А append a CR to every row 
H 
(text,OTCCR) ONAPPEND tie . A write text to file 
ОМОМТІЕ tie A close file 
EXIT: > 0 A exit 
ERR: а handle error to replace old file 


> € 'FILE NAME ERROR' # 15 t ODM > / OTHER ERR 
name . ONTIE tie — 
name ПМЕРА5БЕ tie. 
IE 
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Fig. 2 Draw demo in APL 
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Amusement 
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APL 
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Arrays 

ATP - AppleTalk Transaction Protocol 
Background Processing 

Basic Compar isons 
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Bus Phases 


CASE - Computer Aided Software Engineer ing 
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Color Manager 
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